How to write open-source in PHP 2: Rise value of your package with help of skeleton
This post was updated at February 2021 with fresh know-how.
What is new?
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
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
musthave :)
/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.