If you created a useful PHP library and want to share it with others or reuse it in your other projects, it will be convenient to pack it into a separate package. In this series of articles, we'll discover how to properly organize code into a reusable package, create a structure of the project, write unit tests, create an automatic code style check, implement CI using github actions, and much more. As an example, we will write step by step a small PHP library for syntax highlighting. It will accept text and return highlighted PHP code.
We will split the series into five parts.
- Сreate composer.json and describe the dependencies.
- Write an application for syntax highlighting.
- Autoload classes with Composer
- Install PHPUnit.
- Write unit tests.
- Configure PHPUnit with XML.
- Code coverage.
- Implement a code style check using PHP_CodeSniffer.
- Configure PHP_CodeSniffer with XML.
- Create a git repository
- Create a Readme file.
- Deal with versioning and tagging.
- Publish the package on packagist.org
- Create CI/CD
- Add GitHub Actions for our repository.
1. Creating composer.json
As a first step, let's create a composer file. Composer is a dependency manager for PHP, like npm for Node.js
If you didn't install the composer yet, you can read how to install it here.
Dependencies are described in the composer.json
file. To generate this file automatically, create a directory php-highlight-example for the project, open it and run:
composer init
You will be asked to answer a number of questions:
Package name (<vendor>/<name>) []: your.name/php-highlight-example
<vendor> usually matches your GitHub login, and a name is the name of the package itself.
Description []: A PHP library for highlighting code syntax.
Author []: My Name <my_email@example.com>
Minimum Stability []: (skip this)
Package Type []: library
License []: MIT
Would you like to define your dependencies (require) interactively?
Answer "no". We will add dependencies as we needed them.
Add PSR-4 autoload mapping? Maps namespace ... to the entered relative path. [src/, n to skip]: no
Next, check our composer.json. If everything is correct, enter "yes".
Our composer.json
looks like this:
{ "name": "demyanovs/php-highlight-example", "description": "A PHP library for highlighting code syntax.", "type": "library", "license": "MIT", "authors": [ { "name": "Viacheslav Demianov", "email": "demyanovs@gmail.com" } ], "require": {} }
You can read more about licenses on the Choose a License website.
2. Writing an application
Inside php-highlight-example directory, create the following structure:
. ├── examples | └── index.php ├── src ├── ColorsDto.php | └── Highlighter.php └── composer.json
src/Highlighter.php
src/ColorsDto.php
Note that you need to replace the namespace Demyanovs\PHPHighlight
with yours.
In PHP, you can use namespaces to set aliases for classes and paths, which solves the problem of class name conflicts in PHP when, for example, you use third-party classes or libraries with the same names.
Usually, the namespace is the same as the directory path, but this is optional.
If you are not familiar with the concept of namespaces, you can read more here.
Example of usage:
examples/index.php
3. Autoloading with composer
Now we need to tell the composer where to find our code. We will implement the PSR-4 autoloading standard.
Open composer.json
file and after "require": {}
add
"autoload": { "psr-4": { "Demyanovs\\PHPHighlight\\": "src/" } },
What is PSR?
The PHP Standard Recommendation is a PHP specification published by the PHP Framework Interop Group. It serves the standardization of programming concepts in PHP. Read more.
And finally, to generate an autoloader file, we need to run the command:
composer install
This command will create a vendor folder with an autoloader file. There will be other dependencies, but we don't have any yet.
Now we can see how syntax highlighting works by opening our example file examples/index.php
What's next?
Our code was highlighted with colors, according to our settings. You can choose your colors.
In the next part, we will install PHPUnit and cover our code with tests.