If you are reading this I guess you know what Composer and Packagist are and probably you need to know how to build your own package or you just simply don’t remember all the steps to do it.
Otherwise, you can get some very basic info of Composer here: Wikipedia Composer and if you want to dive into the documentation then you can visit Composer Documentation page. Packagist is the main repository for Composer packages.
Preparation
We will create a package and before writing a line of code, we will compile some basic information. I’m using mine as an example.
- Developer name / Organization: pangodream
- Package name: str-util
- Description: A very simple package
Setting up the project for the package
Create the project folder
In our case, the project folder will be str-util
Create two more folders inside the project one; one for the package code and the other one for testing. The folder structure should be:
str-util /src /test
Create composer.json file
Access the project folder and create composer.json by typing
> composer init
Composer will try to guess some of the configuration values
Once we confirm the file generation, a composer.json file will be in our project folder and it will contain some very similar to this:
{ "name": "pangodream/str-util", "description": "A very simple package", "type": "library", "license": "MIT", "authors": [ { "name": "pangodream", "email": "development@pangodream.es" } ], "minimum-stability": "dev", "require": {} }
So, this is now the content of our project folder:
str-util composer.json /src /test
Edit to complete composer.json
We will add some information about autoloading (“autoload”) and also tell composer our dependencies (“require”). For instance, which is the minimum version of PHP that our library needs to work.
{ "name": "pangodream/str-util", "description": "A very simple package", "type": "library", "license": "MIT", "authors": [ { "name": "pangodream", "email": "development@pangodream.es" } ], "minimum-stability": "dev", "autoload": { "psr-0": { "StrUtil": "src/" } }, "require": { "php": ">=7.0.0" } }
Install composer autoloader
Now we will tell Composer to install autoloader and its code. Like any other vendor, Composer will deploy its own files inside the vendor folder.
> composer install Loading composer repositories with package information Updating dependencies (including require-dev) Nothing to install or update Writing lock file Generating autoload files
Now, the content of the folder is
str-util /composer.json /composer.lock /src /test /vendor /autoload.php /composer /autoload_classmap.php /autoload_namespaces.php /autoload_psr4.php /autoload_real.php /autoload_static.php /ClassLoader.php /installed.json /LICENSE
Write down our package code
Inside the composer.json file, we told composer the path were StrUtil package classes are. So, each time we reference in our code a class qualified with its package name Composer will look into the composer.json file to know where that class file is.
In our case, the package name is StrUtil and the class is Counter (because our class will contain some methods to count words, paragraphs, letters, …).
Inside src folder, let’s create a new folder for our package with the name we gave it inside composer.json: StrUtil, and inside that folder, we will place one of our package classes file. Now, we have this folder hierarchy
/str-util /src /StrUtil /Counter.php
So, when PHP finds a reference to a class with the ‘use’, it will look into composer.json. For instance, let’s say we have a line of code like this
use StrUtil\Counter;
What composer.json file indicates is that StrUtil package is under src folder
"autoload": { "psr-0": { "StrUtil": "src/" } }
So, the Counter.php file containing the Counter class code should be located in
src/StrUtil/Counter.php
Now we know how the class file is located and loaded, let’s write down the code:
<?php /** * Created by Pangodream. * Date: 14/04/2019 * Time: 18:50 */ namespace StrUtil; class Counter { /** * @param string $text The text we want to count the number of words it consist of * @return int The number of words in text */ public static function countWords(string $text){ /** @var int $count To store the result of counting words in text */ $count = 0; //Clean up the string $text = trim($text); /** @var array $words Array containing the words */ $words = explode(" ", $text); //Array size is the number of words in text $count = sizeof($words); return $count; } }
And now we know how to reference that class, let’s create a test file to verify that our class works. We will name this file testStrUtil.php and save it inside the test folder we created before:
str-util /test /testStrUtil.php
<?php /** * Created by Pangodream. * Date: 14/04/2019 * Time: 19:03 */ //Use composer autoload to load class files require_once __DIR__ . "/../vendor/autoload.php"; //Required package/libraries use StrUtil\Counter; $text = "Aequam memento rebus in arduis servare mentem"; $wordCount = Counter::countWords($text); echo "The txt contains ".$wordCount." word(s)\r\n";
Testing our package
From the str-util folder, we are going to invoke the test PHP file and see what happens:
str-util> php test/testStrUtil.php The text contains 7 word(s)
Our package containing only a class is working and now we are ready to publish it.
Repository part: github.com
The next thing we’ll do is creating a new repository with our GitHub account.
Create the repository at github.com
Go to github.com and create a new repository called str-util. It is a good practice to give a repository description and also initialize with a README file. Because you are going to share the package in packagist.org you need to Add a license file, in our case an MIT License.
Add package files to the repository
Now we will make an initial commit to our repository with the files we already have created inside the src folder.
From the str-util folder, execute the following commands:
---->str-util> git init Initialized empty Git repository in C:/cli/str-util/.git/ ---->str-util> git add src
---->str-util> git add composer.json ---->str-util> git commit -m "Initial commit" [master (root-commit) af7bbac] Initial commit 2 file changed, 28 insertions(+) create mode 100644 src/StrUtil/Counter.php
create mode 100644 composer.json ---->str-util> git remote add origin https://github.com/YOUR_USER_NAME/str-util.git ---->str-util> git pull origin master --allow-unrelated-histories From https://github.com/YOUR_USER_NAME/str-util * branch master -> FETCH_HEAD Merge made by the 'recursive' strategy. README.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 README.md ---->str-util> git push origin master fatal: HttpRequestException encountered. Error al enviar la solicitud. Username for 'https://github.com': YOUR_USER_NAME Password for 'https://YOUR_USER_NAME@github.com': Counting objects: 7, done. Delta compression using up to 4 threads. Compressing objects: 100% (4/4), done. Writing objects: 100% (7/7), 928 bytes | 309.00 KiB/s, done. Total 7 (delta 0), reused 0 (delta 0) To https://github.com/YOUR_USER_NAME/str-util.git 16f9ce1..8f91cfa master -> master
Let’s analyze what we have done:
git init
Initialize the Git repository in our local directory. Git will create its hidden files to control operations made on the repository.
git add src
git add composer.json
We are telling Git which files we want to add to the repository. In our case only the src folder and the composer.json file will be synchronized, the rest of the files will stay only in our local machine.
git commit -m "Initial commit"
Our first Initial commit to our local instance of the repository. We haven’t sent anything to github.com until now.
Now we will add an origin (origin means remote repository) to our local repository. This is the reference to our github.com repository. Replace YOUR_USER_NAME with your own Github user name.
git remote add origin https://github.com/YOUR_USER_NAME/str-util.git
If at this point we try to push (send to remote) the commit we made locally, an error will occur because in the remote instance of the repository there are files that don’t exist locally (README file for instance). We cannot send and receive at the same time under normal circumstances, so we will first pull files from origin ignoring possible conflicts:
git pull origin master --allow-unrelated-histories
Now, the README file is in our local repository as well. Now, we can push the commit we made before without any conflicts.
git push origin master
If we take a look to our Github repository, a new folder src should be created and inside it a file named Counter.php
Publishing part: packagist.org
If everything went right, our package is available at Github and ready to be published on Packagist.
Log with your credentials (or using Github) into Packagist.
On the upper right corner, you will find a Submit button. Click on it and a new screen, titled “Submit package” will open.
Copy the URL of your Github repository and paste it inside the text box under “Repository URL (Git/Svn/Hg)”. Your URL should be something like this
https://github.com/YOUR_USER_NAME/str-util
Now press the big green button Check and if our package is OK, the button caption will change to Submit.
Press the Submit button and a new screen, showing the results will appear.
Now you have a new package published in Packagist and anyone who wants to use it only has to type in its project folder:
composer require YOUR_USER_NAME/str-util
In a separate post, we will see how to include our new package in a project and invoke the test function we have created.