How to write open-source in PHP 2: Rise value of your package with help of skeleton
The thephpleague/skeleton is falling behind last 3 years, promoting deprecated practise, so it was dropped. Scrutinizer to PHPStan, ECS added.
After creating a repo, we have to fill it with something useful. Our code! Of course, but we also need some metadata files.
What are they for? Is there some prepared code we can use? What are badges for? I will answer all these questions today.
Other programmers who want to use your package are usually looking for long term value.
To estimate the value they need to answer 4 important questions.
- What is quality of package?
- Does it solve my issue?
- Is it trustworthy?
- How well maintained is it?
Even if you know your code is the best and the cleanest, if they don't trust you, they will never use it.
I will let you think about them a little bit. We will relate with specific files to them in second part of this article.
Use solid skeleton → start solid brand
Now, the first step that can positively influence all the 4 answers is using a skeleton with prepared metadata files. Guys from The PHP League already did the job for you and created a skeleton package.
How to get Skeleton code to your local Repository in 4 steps
- Go to repository on Github and click on Clone or download
- Then Download a ZIP
- Unzip the zip file to your local repository
-
And push new files to Github
git add .
git commit -m "add metadata files"
git push origin master
Great for start, yet obsolete later
This skeleton is great for start and to learn about metadata files.
But when I create my package now, I just copy the most recent package I made, delete /src
and /tests
directories and I'm ready to roll. This is because:
- I upgrade my packages more often then some
skeleton
package
- and because my preferences and required code are evolving
- e.g. A new PHP version is out, I tune my continuous integration (CI) setup etc.
What is the Purpose of these Files?
Now we look on every directory and file and how it's related to the 4 key questions.
Just to remind you, the end user is interested in:
- Quality - What is quality of package?
- Usability - Does it solve my issue? Is it easy to use?
- Trust - Is it trustworthy?
- Maintenance - How well maintained is it?
/src
directory
Meaning
- all your PHP source code will go here
Profit
/tests
directory
Meaning
- all tests for your code in
/src
- basically 1:1 mirror, just every file has
Test
suffix, e.g.
src/Cleaner.php
tests/CleanerTest.php
Profit
- Quality: tested code is perceived better quality
- Trust: I don't have to hope that code works, I can trust the code
.gitattributes
Meaning
- here are all files that are ignored by composer (using the
export-ignore
attribute)
- when somebody will install your package via
composer require you/your-package
, they won't get these files downloaded to /vendor
directory
- usually its metadata files and tests, because application of end user does not need them
Profit
- Usability: Since your package save some internet traffic and space on hard drives, it's a bit more usable.
.gitignore
Meaning
- here are files, that you will have locally but won't be uploaded to the remote git repository
- for packages ignore
composer.lock
, for applications rather not - on Stackoverflow you can find more detailed answer
- also
/vendor
is there, as dependencies are installed by composer
Profit
- Trust: Without this I would not trust you know anything about open-source.
ecs.php
Meaning
- config for Easy Coding Standard - the easiest tool for coding standard
- it checks code to keep it in one compatible coding standard format
Profit
- Quality: coders can contribute in any format their like and the coding standard tool will take care of it for them
phpstan.neon
Meaning
- configuration for PHPStan - the best static analyzer to PHP
- it run on every commit, checking obvious mistakes for you, like call on possible
null
Profit
- Trust: you and your contributors can stop thinking about detailed code and go a relax - everyone can contribute easily
- Quality: tested code is perceived better quality
composer.json
- list of dependencies
- configuration for Packagist, where you need to add your package, so it can be installed by others
- to enable it, you have to:
- go there
- add repository
- go to settings of package, Integration and services and Add Service
- select "Packagist" and add your name and token from your user profile
LICENSE
Meaning
- license goes here
- it's important to have it as every country has different default approach, when this file is missing
- MIT is the easiest to understand open-source license
Profit
- Usability: With licence, I know what I can do with the code. Usually everything.
phpunit.xml
Meaning
- configuration for PHPUnit - testing tool
- this can be used either by end user or Travis
Profit
- Usability: I can run
vendor/bin/phpunit
with no manual configuration. It makes life easy.
README
Meaning
- last but the most important - your welcome article for user
- THE MOST IMPORTANT FILE IN THE PACKAGE!
- Don't worry. We'll talk about writing a good readme later.
Profit
- Usability: If I understand the usage, I can rely to the issue I want to solve.
- Trust: Having code quality, Travis and coverage badges helps to identify the quality of the package.
So that are all files and their purpose.
No time! Fast! Now! → Tell your story with an image
Today people are scanning the text rather then actually reading. That's why badges are so important!
Look on these 2 - what information can we get?
- Test are passing - GOOD
- There is stable tag with "?" coverage - CONFUSING
- Master has 89% test coverage - GOOD
- Last version is probably 2.5, but not sure. Do they update manually? - CONFUSING
- Why is master promoted on first place? Should I use that? - CONFUSING
From Doctrine2 repository.
- Test are passing - GOOD
- Code quality is 10 - GOOD
- Code coverage 93% test coverage - GOOD
- It has 166 downloads. Here it depends on the age of package. → Go check release date! - GOOD
- It's tagged and has stable version. - GOOD
What have we Done Today?
- Where to go when starting a new repository.
- What is the purpose meta files.
- How to enable online services that help us to build better code.
What's next?
- We'll peek on coding standards.
- How do releases work a what is semantic versioning.
- How to pick min PHP version and package versions in composer.
Happy coding!