php[architect] November 2018

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

The Workshop

Producing Packages, Part Two

Joe Ferguson

Last month we started building PHP Easy Math, a small library which can be included in

PHP projects to provide simple methods to do basic addition and subtraction. We’re using

this as an example library to focus on what makes a library “good” we are less worried

about the practical need for and usage of our package.

What Did We Forget?

If you have not yet read Part

1 pause here and go read The

Workshop: Producing Pack-

ages (Part 1). Head over to

github.com/svpernova09/php-easy-math

to get the library code.

At the end of the previous article I

asked readers what we forgot to do in

our library and to reach out to me on

Twitter with the answer. I’m happy to

say MemphisPHP user group leader

Bryce Sharp was the first to answer

correctly (Figure 1).

Pick a License

Licensing any code you write is

incredibly important. Even if you’re not

sharing code with the entire open source

world you still should have a license. If

you are sharing open source code and

there is no license which means no one

is allowed to do anything with your

code! To sort through software licenses

I highly recommend reading Choose a

License^1. Choose a License does a great

job of explaining the benefits of differ-

ent open source licenses. However if

you do not put a license on your code it

is considered proprietary software and

is unable to be used by anyone. The act

of using a permissive license if you are

expressly granting approval for others

to use your code.

Since our PHP Easy Math library is

a very basic package we are using for

learning, we’re going to add the MIT

1 Choose a License:

https://choosealicense.com

License^2 to the library. This will allow

anyone to use our library in their own

projects or modify our code to suite

their needs. However our copyright

must remain intact. You can see we

added our LICENSE file in the repository^3.

One last housekeeping task we’re

going to perform is to rename our

README file to README.md. We’re using

Markdown^4 but Github is not rendering

our markdown because we do not have

a file extension. Once we have renamed

the file our contents will be rendered as

we’d expect and not just as plain text.

Documentation is Key

Do you expect potential users of your

library to read the source code? Of

course not, documentation is import-

ant. It’s the best way to ensure your code

is easy to understand by other develop-

ers. You’ll also ensure you’re explaining

anything which may not be perfectly

obvious to someone else reading or

using the code without getting bogged

down in the internal workings.

In our haste to create our library

we forgot to document our add() and

subtract() methods. While these

are not overly complex methods we

should still add documentation blocks

(doc blocks) to help IDEs with auto

completion as well as generating our

documentation:

Addition is shown in Listing 1.

See Listing 2 for handling subtraction.

2 MIT License:

https://en.wikipedia.org/wiki/MIT_License

3 in the repository:

https://phpa.me/php-easy-math-licensei

4 Markdown:

https://phpa.me/wikip-markdown

Figure 1

Listing 1

1. <?php


2. /**


3. 
   
   
   
   • Sum 2 numbers
   
   
   
   


4. 
   
   
   
   • 
     
   
   
   
   


5. 
   
   
   
   • @param float $x
   
   
   
   


6. 
   
   
   
   • @param float $y
   
   
   
   


7. 
   
   
   
   • @return float
   
   
   
   


8. */


9. public function add($x, $y)


10. {


11. return $x + $y;


12. }

Listing 2

1. <?php


2. /**


3. 
   
   
   
   • Subtract 2 numbers
   
   
   
   


4. 
   
   
   
   • 
     
   
   
   
   


5. 
   
   
   
   • @param float $x
   
   
   
   


6. 
   
   
   
   • @param float $y
   
   
   
   


7. 
   
   
   
   • @return float
   
   
   
   


8. */


9. public function subtract($x, $y)


10. {


11. return $x - $y;


12. }