22CodeIgniter Internals Overview
33##############################
44
5- This guide should help contributors understand how the core of the framework works, and what needs to be done
6- when creating new functionality. Specifically, it details the information needed to create new packages for the
7- core.
5+ This guide should help contributors understand how the core of the framework works,
6+ and what needs to be done when creating new functionality. Specifically, it
7+ details the information needed to create new packages for the core.
88
99Dependencies
1010============
1111
12- All packages should be designed to be completely isolated from the rest of the packages. This will allow
13- them to be used in projects outside of CodeIgniter. Basically, this means that all dependencies should be
14- kept to a minimum. Any dependencies must be able to be passed into the constructor. If you do need to use one
15- of the other core packages, you can create that in the constructor using the Services class, as long as you
16- provide a way for dependencies to override that::
12+ All packages should be designed to be completely isolated from the rest of the
13+ packages, if possible. This will allow them to be used in projects outside of CodeIgniter.
14+ Basically, this means that any dependencies should be kept to a minimum.
15+ Any dependencies must be able to be passed into the constructor. If you do need to use one
16+ of the other core packages, you can create that in the constructor using the
17+ Services class, as long as you provide a way for dependencies to override that::
1718
1819 public function __construct(Foo $foo=null)
1920 {
@@ -26,91 +27,112 @@ Type hinting
2627============
2728
2829PHP7 provides the ability to `type hint <http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration >`_
29- method parameters and return types. Use it where possible. Return type hinting is not always practical, but do try to
30- make it work.
30+ method parameters and return types. Use it where possible. Return type hinting
31+ is not always practical, but do try to make it work.
3132
3233At this time, we are not using strict type hinting.
3334
3435Abstractions
3536============
3637
37- The amount of abstraction required to implement a solution should be the minimal amount required. Every layer of
38- abstraction brings additional levels of technical debt and unnecessary complexity. That said, don't be afraid to
39- use it when it's needed and can help things.
38+ The amount of abstraction required to implement a solution should be the minimal
39+ amount required. Every layer of abstraction brings additional levels of technical
40+ debt and unnecessary complexity. That said, don't be afraid to use it when it's
41+ needed and can help things.
4042
4143* Don't create a new container class when an array will do just fine.
4244* Start simple, refactor as necessary to achieve clean separation of code, but don't overdo it.
4345
4446Testing
4547=======
4648
47- Any new packages submitted to the framework must be accompanied by unit tests. The target is 80%+ coverage of all
48- classes within the package.
49+ Any new packages submitted to the framework must be accompanied by unit tests.
50+ The target is 80%+ code coverage of all classes within the package.
4951
5052* Test only public methods, not protected and private unless the method really needs it due to complexity.
5153* Don't just test that the method works, but test for all fail states, thrown exceptions, and other pathways through your code.
5254
55+ You should be aware of the extra assertions that we have made, provisions for
56+ accessing private properties for testing, and mock services.
57+ We have also made a **CITestStreamFilter ** to capture test output.
58+ Do check out similar tests in ``tests/system/ ``, and read the "Testing" section
59+ in the user guide, before you dig in to your own.
60+
61+ Some testing needs to be done in a separate process, in order to setup the
62+ PHP globals to mimic test situations properly. See
63+ ``tests/system/HTTP/ResponseSendTest `` for an example of this.
64+
5365Namespaces and Files
5466====================
5567
56- All new packages should live under the ``CodeIgniter `` namespace. The package itself will need its own sub-namespace
68+ All new packages should live under the ``CodeIgniter `` namespace.
69+ The package itself will need its own sub-namespace
5770that collects all related files into one grouping, like ``CodeIgniter\HTTP ``.
5871
59- Files MUST be named the same as the class they hold, and they must match the :doc: `Style Guide <styleguide >`, meaning
60- CamelCase class and file names. The should be in their own directory that matches the sub-namespace under the **system **
61- directory.
72+ Files MUST be named the same as the class they hold, and they must match the
73+ :doc: `Style Guide <./styleguide.rst >`, meaning CamelCase class and file names.
74+ They should be in their own directory that matches the sub-namespace under the
75+ **system ** directory.
6276
63- The the Router as an example. The Router lives in the ``CodeIgniter\Router `` namespace. It has two classes,
64- **RouteCollection ** and **Router **, which are in the files, **system/Router/RouteCollection.php ** and
77+ Take the Router class as an example. The Router lives in the ``CodeIgniter\Router ``
78+ namespace. Its two main classes,
79+ **RouteCollection ** and **Router **, are in the files **system/Router/RouteCollection.php ** and
6580**system/Router/Router.php ** respectively.
6681
6782Interfaces
6883----------
6984
70- Most base classes should have an interface defined for them. At the very least this allows them to be easily mocked
71- and passed in other classes as a dependency without breaking the type-hinting. The interface names should match
72- the name of the class with "Interface" appended to it, like ``RouteCollectionInterface ``.
85+ Most base classes should have an interface defined for them.
86+ At the very least this allows them to be easily mocked
87+ and passed to other classes as a dependency, without breaking the type-hinting.
88+ The interface names should match the name of the class with "Interface" appended
89+ to it, like ``RouteCollectionInterface ``.
7390
7491The Router package mentioned above includes the
75- ``CodeIgniter\Router\RouterCollectionInterface `` and ``CodeIgniter\Router\RouterInterface ``
92+ ``CodeIgniter\Router\RouteCollectionInterface `` and ``CodeIgniter\Router\RouterInterface ``
7693interfaces to provide the abstractions for the two classes in the package.
7794
7895Handlers
7996--------
8097
81- When a package supports multiple "drivers", the convention is to place them in a **Handlers ** directory, and
82- name the child classes as Handlers. You will often find that creating a ``BaseHandler `` the child classes can
83- extend to be beneficial in keeping the code DRY.
98+ When a package supports multiple "drivers", the convention is to place them in
99+ a **Handlers ** directory, and name the child classes as Handlers.
100+ You will often find that creating a ``BaseHandler ``, that the child classes can
101+ extend, to be beneficial in keeping the code DRY.
84102
85103See the Log and Session packages for examples.
86104
87105Configuration
88106=============
89107
90- Should the package require user-configurable settings, you should create a new file just for that package under
91- **app/Config **. The file name should generally match the package name.
108+ Should the package require user-configurable settings, you should create a new
109+ file just for that package under **app/Config **.
110+ The file name should generally match the package name.
92111
93112Autoloader
94113==========
95114
96- All files within the package should be added to **system/Config/AutoloadConfig.php **, in the "classmap" property.
97- This is only used for core framework files, and helps to minimize file system scans and keep performance high.
115+ All files within the package should be added to **system/Config/AutoloadConfig.php **,
116+ in the "classmap" property. This is only used for core framework files, and helps
117+ to minimize file system scans and keep performance high.
98118
99119Command-Line Support
100120====================
101121
102- CodeIgniter has never been known for it's strong CLI support. However, if your package could benefit from it, create a
103- new file under **system/Commands **. The class contained within is simply a controller that is intended for CLI
104- usage only. The ``index() `` method should provide a list of available commands provided by that package.
122+ CodeIgniter has never been known for it's strong CLI support. However, if your
123+ package could benefit from it, create a new file under **system/Commands **.
124+ The class contained within is simply a controller that is intended for CLI
125+ usage only. The ``index() `` method should provide a list of available commands
126+ provided by that package.
105127
106- Routes must be added to **system/Config/Routes.php ** using the ``cli() `` method to ensure it is not accessible
107- through the browser, but is restricted to the CLI only.
128+ Routes must be added to **system/Config/Routes.php ** using the ``cli() `` method
129+ to ensure it is not accessible through the browser, but is restricted to the CLI only.
108130
109131See the **MigrationsCommand ** file for an example.
110132
111133Documentation
112134=============
113135
114- All packages must contain appropriate documentation that matches the tone and style of the rest of the user guide.
115- In most cases, the top portion of the package's page should be treated in tutorial fashion, while the second
116- half would be a class reference.
136+ All packages must contain appropriate documentation that matches the tone and
137+ style of the rest of the user guide. In most cases, the top portion of the package's
138+ page should be treated in tutorial fashion, while the second half would be a class reference.
0 commit comments