From ce3cce555289cd91d959f0e348309cff58ff4957 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 28 Jul 2023 10:24:38 +0900 Subject: [PATCH 1/8] docs: add Creating Composer Packages --- .../source/extending/composer_packages.rst | 109 ++++++++++++++++++ user_guide_src/source/extending/index.rst | 1 + user_guide_src/source/general/modules.rst | 6 +- 3 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 user_guide_src/source/extending/composer_packages.rst 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 000000000000..00d68226c77d --- /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 93227128924a..ba6284f5dc0e 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 ae79f5431779..a753be0ba247 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 From c16221b2e6c0acbd68dd35c21b32c869a36cedd9 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 29 Jul 2023 08:25:41 +0900 Subject: [PATCH 2/8] docs: add gitattributes and gitignore --- user_guide_src/source/extending/composer_packages.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst index 00d68226c77d..3557c37855c3 100644 --- a/user_guide_src/source/extending/composer_packages.rst +++ b/user_guide_src/source/extending/composer_packages.rst @@ -16,6 +16,8 @@ Folder Structure Here's a typical directory structure for a Composer package:: your-package-name/ + ├── .gitattributes + ├── .gitignore ├── README.md ├── composer.json ├── src/ From c9cc01c0badd63382a07784f50ccb11ab6d84b39 Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 29 Jul 2023 09:29:11 +0900 Subject: [PATCH 3/8] docs: add about DevKit --- .../source/extending/composer_packages.rst | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst index 3557c37855c3..711b339c2065 100644 --- a/user_guide_src/source/extending/composer_packages.rst +++ b/user_guide_src/source/extending/composer_packages.rst @@ -89,6 +89,76 @@ be ``YourVendor``. So you would write like the following:: This setting instructs Composer to autoload the source code for your package. +*************************** +Preparing Development Tools +*************************** + +There are many tools that help ensure quality code. So you should use them. +You can easily install and configure such tools with +`CodeIgniter DevKit `_. + +Installing DevKit +================= + +In the root of your package directory, run the following commands:: + + > composer config minimum-stability dev + > composer config prefer-stable true + > composer require --dev codeigniter4/devkit + +The DevKit installs various Composer packages that helps your development, and +installs templates for them in **vendor/codeigniter4/devkit/src/Template**. +Copy the files in it to your project root folder, and edit them for your needs. + +Configuring Coding Standards Fixer +================================== + +DevKit provides Coding Standards Fixer with +`CodeIgniter Coding Standard `_ +based on `PHP-CS-Fixer `_. + +Copy **vendor/codeigniter4/devkit/src/Template/.php-cs-fixer.dist.php** to your +project root folder. + +Create the **build** folder for the cache file:: + + your-package-name/ + ├── .php-cs-fixer.dist.php + ├── build/ + +Open **.php-cs-fixer.dist.php** in your editor, and fix the folder path:: + + --- a/.php-cs-fixer.dist.php + +++ b/.php-cs-fixer.dist.php + @@ -7,7 +7,7 @@ use PhpCsFixer\Finder; + $finder = Finder::create() + ->files() + ->in([ + - __DIR__ . '/app/', + + __DIR__ . '/src/', + __DIR__ . '/tests/', + ]) + ->exclude([ + +That't it. Now you can run Coding Standards Fixer:: + + > vendor/bin/php-cs-fixer fix --ansi --verbose --diff + +If you add ``scripts.cs-fix`` in your **composer.json**, you can run it with +``composer cs-fix`` command:: + + --- a/composer.json + +++ b/composer.json + @@ -23,5 +23,8 @@ + "allow-plugins": { + "phpstan/extension-installer": true + } + + }, + + "scripts": { + + "cs-fix": "php-cs-fixer fix --ansi --verbose --diff" + } + } + ************ Config Files ************ From bab7227165e0862281fb15ed6dca1f0b741cdf6e Mon Sep 17 00:00:00 2001 From: kenjis Date: Sat, 29 Jul 2023 09:29:25 +0900 Subject: [PATCH 4/8] docs: add References --- .../source/extending/composer_packages.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst index 711b339c2065..daf62746a7a9 100644 --- a/user_guide_src/source/extending/composer_packages.rst +++ b/user_guide_src/source/extending/composer_packages.rst @@ -179,3 +179,16 @@ 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 `. + +********** +References +********** + +We have published some official packages. You can use these packages as references +when creating your own packages: + +- https://github.com/codeigniter4/shield +- https://github.com/codeigniter4/settings +- https://github.com/codeigniter4/tasks +- https://github.com/codeigniter4/cache + From add666c332f9216d1b4e5ca768bf2b8a337d04e3 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 31 Jul 2023 09:55:18 +0900 Subject: [PATCH 5/8] docs: add LICENSE in Folder Structure --- user_guide_src/source/extending/composer_packages.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst index daf62746a7a9..b6f1c5118b1c 100644 --- a/user_guide_src/source/extending/composer_packages.rst +++ b/user_guide_src/source/extending/composer_packages.rst @@ -18,6 +18,7 @@ Here's a typical directory structure for a Composer package:: your-package-name/ ├── .gitattributes ├── .gitignore + ├── LICENSE ├── README.md ├── composer.json ├── src/ From b21eb76bfb15c32c5080fe953cdfd9e0b7285c17 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 31 Jul 2023 13:00:51 +0900 Subject: [PATCH 6/8] docs: fix by proofreading Co-authored-by: John Paul E. Balandan, CPA --- user_guide_src/source/extending/composer_packages.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst index b6f1c5118b1c..4468627df236 100644 --- a/user_guide_src/source/extending/composer_packages.rst +++ b/user_guide_src/source/extending/composer_packages.rst @@ -68,10 +68,10 @@ 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. + such as your name 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. +Thus, it is important to make the name unique to distinguish it from other packages. Uniqueness is especially important when publishing. Namespace From 6684f7a8db0b6195154b7eebe4e8c5ffdf6d0e20 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 31 Jul 2023 12:59:05 +0900 Subject: [PATCH 7/8] docs: remove `>` so that the commands can be copy pasted --- user_guide_src/source/extending/composer_packages.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst index 4468627df236..333557b4f8e4 100644 --- a/user_guide_src/source/extending/composer_packages.rst +++ b/user_guide_src/source/extending/composer_packages.rst @@ -101,11 +101,13 @@ You can easily install and configure such tools with Installing DevKit ================= -In the root of your package directory, run the following commands:: +In the root of your package directory, run the following commands: - > composer config minimum-stability dev - > composer config prefer-stable true - > composer require --dev codeigniter4/devkit +.. code-block:: console + + composer config minimum-stability dev + composer config prefer-stable true + composer require --dev codeigniter4/devkit The DevKit installs various Composer packages that helps your development, and installs templates for them in **vendor/codeigniter4/devkit/src/Template**. From 1a96f24538451f40064393a3da5cab09b7b02981 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 31 Jul 2023 13:05:38 +0900 Subject: [PATCH 8/8] docs: stop representation by diff --- .../source/extending/composer_packages.rst | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/user_guide_src/source/extending/composer_packages.rst b/user_guide_src/source/extending/composer_packages.rst index 333557b4f8e4..120307a2dfc7 100644 --- a/user_guide_src/source/extending/composer_packages.rst +++ b/user_guide_src/source/extending/composer_packages.rst @@ -150,17 +150,13 @@ That't it. Now you can run Coding Standards Fixer:: If you add ``scripts.cs-fix`` in your **composer.json**, you can run it with ``composer cs-fix`` command:: - --- a/composer.json - +++ b/composer.json - @@ -23,5 +23,8 @@ - "allow-plugins": { - "phpstan/extension-installer": true - } - + }, - + "scripts": { - + "cs-fix": "php-cs-fixer fix --ansi --verbose --diff" - } - } + { + // ... + }, + "scripts": { + "cs-fix": "php-cs-fixer fix --ansi --verbose --diff" + } + } ************ Config Files