diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst new file mode 100644 index 0000000000..00d68226c7 --- /dev/null +++ b/user_guide_src/source/extending/composer_packages.rst @@ -0,0 +1,109 @@ +########################## +Creating Composer Packages +########################## + +You can make the :doc:`../general/modules` you create into Composer packages, +or can create a Composer package for CodeIgniter 4. + +.. contents:: + :local: + :depth: 2 + +**************** +Folder Structure +**************** + +Here's a typical directory structure for a Composer package:: + + your-package-name/ + ├── README.md + ├── composer.json + ├── src/ + │   └── YourClass.php + └── tests/ + └── YourClassTest.php + +********************** +Creating composer.json +********************** + +In the root of your package directory, create a **composer.json** file. This file +defines metadata about your package and its dependencies. + +The ``composer init`` command helps you create it. + +For example, **composer.json** might look like this:: + + { + "name": "your-vendor/your-package", + "description": "Your package description", + "type": "library", + "license": "MIT", + "autoload": { + "psr-4": { + "YourVendor\\YourPackage\\": "src/" + } + }, + "authors": [ + { + "name": "Your Name", + "email": "yourname@example.com" + } + ], + "require": { + // Any dependencies required by your package go here + }, + "require-dev": { + // Any development dependencies (e.g., PHPUnit) go here + } + } + +Package Name +============ + +The ``name`` field is important here. Package names are generally written in the +format "vendor-name/package-name" with all lowercase. Here is a common example: + +- ``your-vendor-name``: The name that identifies the vendor (creator of the package), + such as the name of you or your organization. +- ``your-package-name``: The name of the package you are creating. + +Thus, it is important to make the name unique and distinguish it from other packages. +Uniqueness is especially important when publishing. + +Namespace +========= + +The package name then determines the vendor namespace in ``autoload.psr4``. + +If your package name is ``your-vendor/your-package``, the vendor namespace must +be ``YourVendor``. So you would write like the following:: + + "autoload": { + "psr-4": { + "YourVendor\\YourPackage\\": "src/" + } + }, + +This setting instructs Composer to autoload the source code for your package. + +************ +Config Files +************ + +Allowing Users to Override Settings +=================================== + +If your package has a configuration file and you want users to be able to override +the settings, use :php:func:`config()` with the short classname like ``config('YourConfig')`` +to call the configuration file. + +Users can then override the package configuration by placing a configuration class +with the same short classname in **app/Config** that extends the package Config +class like ``YourVendor\YourPackage\Config\YourConfig``. + +Overriding Settings in app/Config +================================= + +If you need to override or add to known configurations in the **app/Config** folder, +you can use :ref:`Implicit Registrars `. diff --git a/user_guide_src/source/extending/index.rst b/user_guide_src/source/extending/index.rst index 9322712892..ba6284f5dc 100644 --- a/user_guide_src/source/extending/index.rst +++ b/user_guide_src/source/extending/index.rst @@ -12,4 +12,5 @@ CodeIgniter 4 has been designed to be easy to extend or build upon. events basecontroller authentication + composer_packages contributing diff --git a/user_guide_src/source/general/modules.rst b/user_guide_src/source/general/modules.rst index ae79f54317..a753be0ba2 100644 --- a/user_guide_src/source/general/modules.rst +++ b/user_guide_src/source/general/modules.rst @@ -3,10 +3,14 @@ Code Modules ############ CodeIgniter supports a form of code modularization to help you create reusable code. Modules are typically -centered around a specific subject, and can be thought of as mini-applications within your larger application. Any +centered around a specific subject, and can be thought of as mini-applications within your larger application. + +Any of the standard file types within the framework are supported, like controllers, models, views, config files, helpers, language files, etc. Modules may contain as few, or as many, of these as you like. +If you want to create a module as a Composer package, see also :doc:`../extending/composer_packages`. + .. contents:: :local: :depth: 2