php[architect] November 2018

34 \ November 2018 \ http://www.phparch.com

Producing Packages, Part Two

The Workshop

If we click on Graphs and Class hier-

archy diagram we see the diagram in

Figure 6 showing our class hierarchy.

If we click on Reports and Errors

we can see what phpDocumentor is

flagging as a compilation error because

we’re missing summaries on our classes

and our class files as shown in Figure 7.

Going back to our Addition class

we can add a file summary and a class

summary doc blocks as the first block

after the PHP open tag.

src/Addition.php is shown in Listing

3. src/Subtraction.php is shown in List-
   ing 4.
   Now we can run our command again
   to regenerate the documentation and
   we’ll no longer see any errors when
   clicking on Reports and Errors.

Beyond Doc Blocks

While doc blocks are great for telling

other developers and their code editors

about your code it’s also important to

speak directly to developers about how

to use your library. This starts with our

README.md file. We should add instruc-

tions on how to require our library

with Composer, what PHP versions we

require, how to get help, and anything

else we may find relevant to explain

about our project. We can also add

a fancy badge to be displayed on our

repository to show our current build

status.

We start with our library name and

our Travis-CI^8 badge. You can get your

repositories badge by visiting your build

and clicking on the build status badge.

Since we’re using Markdown on Github

we’ll select the Markdown option. Next

we’ll want to describe what our library

does and why it is useful. We’ll add the

contents of Listing 5 to README.md.

Now we’ll want to instruct users how

to include our library in their PHP proj-

ect via Composer and how to use our

code. Add the text in Listing 6.

8 Travis-CI: https://travis-ci.org

Because we’re including example.

php which has usage examples of both

classes our library contains we’ll link

to it from our README.md. If you want to

paste your example code directly into

the README.md file is perfectly fine as

well. example.php is shown in Listing 7.

Pull Requests And Issues

The last two things we need to add

to our README.md are how to get help

and how to contribute. While these

two things are quite easy to say they

are much harder to do. Do you really

want pull requests? If not then leave the

section off. There is nothing wrong with

publishing code and never merging a

pull request or helping anyone with

issues they may have. “The Dude” from

the movie “The Big Lebowski” said it

best: “You’re not wrong Walter. You’re

just an ***hole.“. If this is your intent

why did you even bother open sourcing

your code? Reviewing PRs and listen-

ing to user feedback is part of the open

source culture.

You’re reading this magazine to learn

how to be a better developer. Be a better

developer by encouraging your users to

ask for help and listening to users who

contribute code back to your projects.

Don’t be an ***hole like the Walter

character. We should all be good open

source citizens and give back where we

can. Showing your users you care about

the issues they may run into and you

care about others wanting to improve

Figure 6 Figure 7

Listing 3

1. <?php


2. /**


3. 
   
   
   
   • \EasyMath\Addition Class
   
   
   
   


4. */


5. 
   


6. namespace EasyMath;


7. 
   


8. /**


9. 
   
   
   
   • Class containing addition methods
   
   
   
   


10. */


11. class Addition

Listing 4

1. <?php


2. /**


3. 
   
   
   
   • \EasyMath\Subtraction Class
   
   
   
   


4. */


5. 
   


6. namespace EasyMath;


7. 
   


8. /**


9. 
   
   
   
   • Class containing subtraction methods
   
   
   
   


10. */


11. class Subtraction