diff options
Diffstat (limited to 'user_guide_src/source')
| -rw-r--r-- | user_guide_src/source/changelog.rst | 32 | ||||
| -rw-r--r-- | user_guide_src/source/general/styleguide.rst | 120 | ||||
| -rw-r--r-- | user_guide_src/source/installation/upgrade_300.rst | 37 | ||||
| -rw-r--r-- | user_guide_src/source/libraries/migration.rst | 2 | ||||
| -rw-r--r-- | user_guide_src/source/tutorial/news_section.rst | 4 |
5 files changed, 77 insertions, 118 deletions
diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst index 2c2da6aaa..07dae1fdc 100644 --- a/user_guide_src/source/changelog.rst +++ b/user_guide_src/source/changelog.rst @@ -60,12 +60,11 @@ Release Date: Not Released - Helpers - :doc:`Date Helper <helpers/date_helper>` changes include: - - ``now()`` now works with all timezone strings supported by PHP. - - Added an optional third parameter to ``timespan()`` that constrains the number of time units displayed. - - Added an optional parameter to ``timezone_menu()`` that allows more attributes to be added to the generated select tag. + - :php:func:`now()` now works with all timezone strings supported by PHP. + - Added an optional third parameter to :php:func:`timespan()` that constrains the number of time units displayed. + - Added an optional parameter to :php:func:`timezone_menu()` that allows more attributes to be added to the generated select tag. - Deprecated ``standard_date()``, which now just uses the native ``date()`` with `DateTime constants <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_. - - Added function ``date_range()`` that generates a list of dates between a specified period. - - ``create_captcha()`` accepts additional colors parameter, allowing for color customization. + - Added function :php:func:`date_range()` that generates a list of dates between a specified period. - :doc:`URL Helper <helpers/url_helper>` changes include: - Deprecated *separator* options **dash** and **underscore** for function :php:func:`url_title()` (they are only aliases for '-' and '_' respectively). - :php:func:`url_title()` will now trim extra dashes from beginning and end. @@ -244,7 +243,6 @@ Release Date: Not Released - Added support for named parameters in error messages. - :doc:`Language <libraries/language>` line keys must now be prefixed with **form_validation_**. - Added rule **alpha_numeric_spaces**. - - Added method ``has_rule()`` to determine if a rule exists. - Added support for setting :doc:`Table <libraries/table>` class defaults in a config file. - :doc:`Caching Library <libraries/caching>` changes include: - Added Wincache driver. @@ -341,16 +339,15 @@ Bug fixes for 3.0 - Fixed a bug where ``unlink()`` raised an error if cache file did not exist when you try to delete it. - Fixed a bug (#181) where a mis-spelling was in the form validation language file. -- Fixed a bug (#159, #163) that mishandled Query Builder nested transactions because _trans_depth was not getting incremented. +- Fixed a bug (#159, #163) - :doc:`Query Builder <database/query_builder>` nested transactions didn't work properly due to ``_trans_depth`` not being incremented. - Fixed a bug (#737, #75) - :doc:`Pagination <libraries/pagination>` anchor class was not set properly when using initialize method. -- Fixed a bug (#419) - ``auto_link()`` now recognizes URLs that come after a word boundary. +- Fixed a bug (#419) - :php:func:`auto_link()` didn't recognize URLs that come after a word boundary. - Fixed a bug (#724) - :doc:`Form Validation Library <libraries/form_validation>` rule **is_unique** didn't check if a database connection exists. - Fixed a bug (#647) - :doc:`Zip Library <libraries/zip>` internal method ``_get_mod_time()`` didn't suppress possible "stat failed" errors generated by ``filemtime()``. -- Fixed a bug (#608) - Fixes an issue with the Image_lib class not clearing properties completely. -- Fixed a bug (#157, #174) - the Image_lib clear() function now resets all variables to their default values. -- Fixed a bug where using $this->dbforge->create_table() with PostgreSQL database could lead to fetching whole table. -- Fixed a bug (#795) - Fixed form method and accept-charset when passing an empty array. -- Fixed a bug (#797) - timespan() was using incorrect seconds for year and month. +- Fixed a bug (#157, #174) - :doc:`Image Manipulation Library <libraries/image_lib>` method ``clear()`` didn't completely clear properties. +- Fixed a bug where :doc:`Database Forge <database/forge>` method ``create_table()`` with PostgreSQL database could lead to fetching the whole table. +- Fixed a bug (#795) - :doc:`Form Helper <helpers/form_helper>` :php:func:`form_open()` didn't add the default form *method* and *accept-charset* when an empty array is passed to it. +- Fixed a bug (#797) - :php:func:`timespan()` was using incorrect seconds for year and month. - Fixed a bug in CI_Cart::contents() where if called without a TRUE (or equal) parameter, it would fail due to a typo. - Fixed a bug (#696) - make oci_execute() calls inside num_rows() non-committing, since they are only there to reset which row is next in line for oci_fetch calls and thus don't need to be committed. - Fixed a bug (#406) - SQLSRV DB driver not returning resource on ``db_pconnect()``. @@ -464,7 +461,7 @@ Bug fixes for 3.0 - Fixed a bug (#1255) - :doc:`User Agent Library <libraries/user_agent>` method ``is_referral()`` only checked if ``$_SERVER['HTTP_REFERER']`` exists. - Fixed a bug (#1146) - :doc:`Download Helper <helpers/download_helper>` function ``force_download()`` incorrectly sent *Cache-Control* directives *pre-check* and *post-check* to Internet Explorer. - Fixed a bug (#1811) - :doc:`URI Library <libraries/uri>` didn't properly cache segments for ``uri_to_assoc()`` and ``ruri_to_assoc()``. -- Fixed a bug (#1506) - :doc:`Form Helper <helpers/form_helper>` set empty *name* attributes. +- Fixed a bug (#1506) - :doc:`Form Helpers <helpers/form_helper>` set empty *name* attributes. - Fixed a bug (#59) - :doc:`Query Builder <database/query_builder>` method ``count_all_results()`` ignored the DISTINCT clause. - Fixed a bug (#1624) - :doc:`Form Validation Library <libraries/form_validation>` rule **matches** didn't property handle array field names. - Fixed a bug (#1630) - :doc:`Form Helper <helpers/form_helper>` function ``set_value()`` didn't escape HTML entities. @@ -487,9 +484,10 @@ Bug fixes for 3.0 - Fixed a bug - :doc:`DB result <database/results>` method ``list_fields()`` didn't reset its field pointer for the *mysql*, *mysqli* and *mssql* drivers. - Fixed a bug (#73) - :doc:`Security Library <libraries/security>` method ``sanitize_filename()`` could be tricked by an XSS attack. - Fixed a bug (#2211) - :doc:`Migration Library <libraries/migration>` extensions couldn't execute ``CI_Migration::__construct()``. -- Fixed a bug (#2255) where ``smtp_timeout`` was not being applied to read and writes for the socket. -- Fixed a bug (#2239) of missing subject when using ``bcc_batch_mode``. -- Fixed a bug (#2236) - :doc:`Form Helper <helpers/form_helper>` incorrectly determined the value to return in method ``set_value()``. +- Fixed a bug (#2255) - :doc:`Email Library <libraries/email>` didn't apply ``smtp_timeout``to socket reads and writes. +- Fixed a bug (#2239) - :doc:`Email Library <libraries/email>` improperly handled the Subject when used with ``bcc_batch_mode`` resulting in E_WARNING messages and an empty Subject. +- Fixed a bug (#2234) - :doc:`Query Builder <database/query_builder>` didn't reset JOIN cache for write-type queries. +- Fixed a bug (#2298) - :doc:`Database Results <database/results>` method `next_row()` kept returning the last row, allowing for infinite loops. Version 2.1.3 ============= diff --git a/user_guide_src/source/general/styleguide.rst b/user_guide_src/source/general/styleguide.rst index 99bc056f7..144b362f5 100644 --- a/user_guide_src/source/general/styleguide.rst +++ b/user_guide_src/source/general/styleguide.rst @@ -3,8 +3,10 @@ PHP Style Guide ############### -The following page describes the use of coding rules adhered to when -developing CodeIgniter. +The following page describes the coding styles adhered to when +contributing to the development of CodeIgniter. There is no requirement +to use these styles in your own CodeIgniter application, though they +are recommended. .. contents:: Table of Contents @@ -72,14 +74,15 @@ identify a file as being complete and not truncated. /* End of file myfile.php */ /* Location: ./system/modules/mymodule/myfile.php */ +.. note:: There should be no empty line or newline character(s) following + the closing comments. If you happen to see one when + submitting a pull request, please check your IDE settings and fix it. + Class and Method Naming ======================= Class names should always start with an uppercase letter. Multiple words -should be separated with an underscore, and not CamelCased. All other -class methods should be entirely lowercased and named to clearly -indicate their function, preferably including a verb. Try to avoid -overly long and verbose names. +should be separated with an underscore, and not CamelCased. **INCORRECT**:: @@ -100,7 +103,10 @@ overly long and verbose names. } } -Examples of improper and proper method naming: +Class methods should be entirely lowercased and named to clearly +indicate their function, preferably including a verb. Try to avoid +overly long and verbose names. Multiple words should be separated +with an underscore. **INCORRECT**:: @@ -117,8 +123,8 @@ Examples of improper and proper method naming: Variable Names ============== -The guidelines for variable naming is very similar to that used for -class methods. Namely, variables should contain only lowercase letters, +The guidelines for variable naming are very similar to those used for +class methods. Variables should contain only lowercase letters, use underscore separators, and be reasonably named to indicate their purpose and contents. Very short, non-word variables should only be used as iterators in for() loops. @@ -242,10 +248,10 @@ uppercase. Logical Operators ================= -Use of **\|\|** is discouraged as its clarity on some output devices is -low (looking like the number 11 for instance). **&&** is preferred over -**AND** but either are acceptable, and a space should always precede and -follow **!**. +Use of the ``||`` "or" comparison operator is discouraged, as its clarity +on some output devices is low (looking like the number 11, for instance). +``&&`` is preferred over ``AND`` but either are acceptable, and a space should +always precede and follow ``!``. **INCORRECT**:: @@ -318,14 +324,9 @@ other numbers) become strings of digits, and boolean TRUE becomes "1":: Debugging Code ============== -No debugging code can be left in place for submitted add-ons unless it -is commented out, i.e. no var_dump(), print_r(), die(), and exit() -calls that were used while creating the add-on, unless they are -commented out. - -:: - - // print_r($foo); +Do not leave debugging code in your submissions, even when commented out. +Things such as ``var_dump()``, ``print_r()``, ``die()``/``exit()`` should not be included +in your code unless it serves a specific purpose other than debugging. Whitespace in Files =================== @@ -333,73 +334,26 @@ Whitespace in Files No whitespace can precede the opening PHP tag or follow the closing PHP tag. Output is buffered, so whitespace in your files can cause output to begin before CodeIgniter outputs its content, leading to errors and an -inability for CodeIgniter to send proper headers. In the examples below, -select the text with your mouse to reveal the incorrect whitespace. +inability for CodeIgniter to send proper headers. Compatibility ============= -Unless specifically mentioned in your add-on's documentation, all code -must be compatible with PHP version 5.1+. Additionally, do not use PHP -functions that require non-default libraries to be installed unless your -code contains an alternative method when the function is not available, -or you implicitly document that your add-on requires said PHP libraries. - -Class and File Names using Common Words -======================================= - -When your class or filename is a common word, or might quite likely be -identically named in another PHP script, provide a unique prefix to help -prevent collision. Always realize that your end users may be running -other add-ons or third party PHP scripts. Choose a prefix that is unique -to your identity as a developer or company. - -**INCORRECT**:: - - class Email pi.email.php - class Xml ext.xml.php - class Import mod.import.php - -**CORRECT**:: - - class Pre_email pi.pre_email.php - class Pre_xml ext.pre_xml.php - class Pre_import mod.pre_import.php - -Database Table Names -==================== - -Any tables that your add-on might use must use the 'exp\_' prefix, -followed by a prefix uniquely identifying you as the developer or -company, and then a short descriptive table name. You do not need to be -concerned about the database prefix being used on the user's -installation, as CodeIgniter's database class will automatically convert -'exp\_' to what is actually being used. - -**INCORRECT**:: - - email_addresses // missing both prefixes - pre_email_addresses // missing exp_ prefix - exp_email_addresses // missing unique prefix - -**CORRECT**:: - - exp_pre_email_addresses +CodeIgniter requires a minimum PHP version of 5.2.4. Your code must either +be compatible with this minimum requirement, provide a suitable fallback, +or be an optional feature that dies quietly without affecting a user's +application. -.. note:: Be mindful that MySQL has a limit of 64 characters for table - names. This should not be an issue as table names that would exceed this - would likely have unreasonable names. For instance, the following table - name exceeds this limitation by one character. Silly, no? - **exp_pre_email_addresses_of_registered_users_in_seattle_washington** +Additionally, do not use PHP functions that require non-default libraries +to be installed unless your code contains an alternative method when the +function is not available. One File per Class ================== -Use separate files for each class your add-on uses, unless the classes -are *closely related*. An example of CodeIgniter files that contains -multiple classes is the Database class file, which contains both the DB -class and the DB_Cache class, and the Magpie plugin, which contains -both the Magpie and Snoopy classes. +Use separate files for each class, unless the classes are *closely related*. +An example of a CodeIgniter file that contains multiple classes is the +Xmlrpc library file. Whitespace ========== @@ -536,8 +490,8 @@ functions and increase readability. Localized Text ============== -Any text that is output in the control panel should use language -variables in your lang file to allow localization. +CodeIgniter libraries should take advantage of corresponding language files +whenever possible. **INCORRECT**:: @@ -550,7 +504,7 @@ variables in your lang file to allow localization. Private Methods and Variables ============================= -Methods and variables that are only accessed internally by your class, +Methods and variables that are only accessed internally, such as utility and helper functions that your public methods use for code abstraction, should be prefixed with an underscore. @@ -567,7 +521,7 @@ hidden to meet this requirement. For instance, never access a variable that you did not set yourself (such as ``$_POST`` array keys) without first checking to see that it ``isset()``. -Make sure that while developing your add-on, error reporting is enabled +Make sure that your dev environment has error reporting enabled for ALL users, and that display_errors is enabled in the PHP environment. You can check this setting with:: diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst index a3ea01d02..02841ab6e 100644 --- a/user_guide_src/source/installation/upgrade_300.rst +++ b/user_guide_src/source/installation/upgrade_300.rst @@ -1,5 +1,5 @@ ############################# -Upgrading from 2.1.2 to 3.0.0 +Upgrading from 2.1.3 to 3.0.0 ############################# .. note:: These upgrade notes are for a version that is yet to be released. @@ -104,9 +104,9 @@ regular expression:: (.+) // matches ANYTHING (:any) // matches any character, except for '/' -******************************************* -Step 9: Update your librararies' file names -******************************************* +***************************************** +Step 9: Update your libraries' file names +***************************************** CodeIgniter 3.0 only allows library file names to be named in a *ucfirst* manner (meaning that the first letter of the class name must be a capital). For example, @@ -136,8 +136,15 @@ Step 10: Check the calls to Array Helper's element() and elements() functions The default return value of these functions, when the required elements don't exist, has been changed from FALSE to NULL. +*********************************************************************** +Step 11: Check the calls to Directory Helper's directory_map() function +*********************************************************************** + +In the resulting array, directories now end with a trailing directory +separator (i.e. a slash, usually). + ************************************************************* -Step 11: Update usage of Database Forge's drop_table() method +Step 12: Update usage of Database Forge's drop_table() method ************************************************************* Up until now, ``drop_table()`` added an IF EXISTS clause by default or it didn't work @@ -159,7 +166,7 @@ If your application relies on IF EXISTS, you'll have to change its usage. all drivers with the exception of ODBC. *********************************************************** -Step 12: Change usage of Email library with multiple emails +Step 13: Change usage of Email library with multiple emails *********************************************************** The :doc:`Email Library <../libraries/email>` will automatically clear the @@ -174,7 +181,7 @@ pass FALSE as the first parameter in the ``send()`` method: } *************************************************** -Step 13: Update your Form_validation language lines +Step 14: Update your Form_validation language lines *************************************************** Two improvements have been made to the :doc:`Form Validation Library @@ -205,7 +212,7 @@ files and error messages format: later. **************************************************************** -Step 14: Remove usage of (previously) deprecated functionalities +Step 15: Remove usage of (previously) deprecated functionalities **************************************************************** In addition to the ``$autoload['core']`` configuration setting, there's a @@ -238,7 +245,7 @@ Security helper do_hash() :doc:`Security Helper <../helpers/security_helper>` function ``do_hash()`` is now just an alias for PHP's native ``hash()`` function. It is deprecated and scheduled for removal in CodeIgniter 3.1+. -.. note:: This function is still available, but you're strongly encouraged to remove it's usage sooner +.. note:: This function is still available, but you're strongly encouraged to remove its usage sooner rather than later. File helper read_file() @@ -248,7 +255,7 @@ File helper read_file() PHP's native ``file_get_contents()`` function. It is deprecated and scheduled for removal in CodeIgniter 3.1+. -.. note:: This function is still available, but you're strongly encouraged to remove it's usage sooner +.. note:: This function is still available, but you're strongly encouraged to remove its usage sooner rather than later. String helper repeater() @@ -257,7 +264,7 @@ String helper repeater() :doc:`String Helper <../helpers/string_helper>` function :php:func:`repeater()` is now just an alias for PHP's native ``str_repeat()`` function. It is deprecated and scheduled for removal in CodeIgniter 3.1+. -.. note:: This function is still available, but you're strongly encouraged to remove it's usage sooner +.. note:: This function is still available, but you're strongly encouraged to remove its usage sooner rather than later. String helper trim_slashes() @@ -267,7 +274,7 @@ String helper trim_slashes() for PHP's native ``trim()`` function (with a slash passed as its second argument). It is deprecated and scheduled for removal in CodeIgniter 3.1+. -.. note:: This function is still available, but you're strongly encouraged to remove it's usage sooner +.. note:: This function is still available, but you're strongly encouraged to remove its usage sooner rather than later. Email helper functions @@ -292,7 +299,7 @@ Date helper standard_date() to the availability of native PHP `constants <http://www.php.net/manual/en/class.datetime.php#datetime.constants.types>`_, which when combined with ``date()`` provide the same functionality. Furthermore, they have the exact same names as the ones supported by ``standard_date()``. Here are examples of how to replace -it's usage: +its usage: :: @@ -308,7 +315,7 @@ it's usage: // Replacement date(DATE_ATOM, $time); -.. note:: This function is still available, but you're strongly encouraged to remove its' usage sooner +.. note:: This function is still available, but you're strongly encouraged to remove its usage sooner rather than later as it is scheduled for removal in CodeIgniter 3.1+. Pagination library 'anchor_class' setting @@ -320,7 +327,7 @@ attribute to your anchors via the 'attributes' configuration setting. This inclu As a result of that, the 'anchor_class' setting is now deprecated and scheduled for removal in CodeIgniter 3.1+. -.. note:: This setting is still available, but you're strongly encouraged to remove its' usage sooner +.. note:: This setting is still available, but you're strongly encouraged to remove its usage sooner rather than later. String helper random_string() types 'unique' and 'encrypt' diff --git a/user_guide_src/source/libraries/migration.rst b/user_guide_src/source/libraries/migration.rst index 9a7b10d64..b734f5c34 100644 --- a/user_guide_src/source/libraries/migration.rst +++ b/user_guide_src/source/libraries/migration.rst @@ -10,7 +10,7 @@ need to be run against the production machines next time you deploy. The database table **migration** tracks which migrations have already been run so all you have to do is update your application files and -call **$this->migrate->current()** to work out which migrations should be run. +call **$this->migration->current()** to work out which migrations should be run. The current version is found in **config/migration.php**. ******************** diff --git a/user_guide_src/source/tutorial/news_section.rst b/user_guide_src/source/tutorial/news_section.rst index 833e34ead..d7754e9f3 100644 --- a/user_guide_src/source/tutorial/news_section.rst +++ b/user_guide_src/source/tutorial/news_section.rst @@ -162,7 +162,7 @@ The news overview page is now done, but a page to display individual news items is still absent. The model created earlier is made in such way that it can easily be used for this functionality. You only need to add some code to the controller and create a new view. Go back to the -news controller and add the following lines to the file. +news controller and update ``view()`` with the following: :: @@ -211,4 +211,4 @@ a slug to the view method in the news controller. $route['default_controller'] = 'pages/view'; Point your browser to your document root, followed by index.php/news and -watch your news page.
\ No newline at end of file +watch your news page. |