init

.gitignore

@@ -0,0 +1,4 @@
+composer.phar
+vendor/
+.idea/
+.phpunit.result.cache

LICENCE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020 Elliot J. Reed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -0,0 +1,69 @@
+# PHP Package Boilerplate / Example Project
+
+This repository shows a basic setup for a PHP package or application in PHP.
+
+## PHP Versions
+
+This version will work on PHP version 8.0 and above.
+
+For a version which is compatible with PHP 7.4 and above select the 7.4 Git tag ([github.com/elliotjreed/php-package-boilerplate/tree/7.4](https://github.com/elliotjreed/php-package-boilerplate/tree/7.4)).
+
+## Getting Started
+
+PHP 8.0 or above and Composer is expected to be installed on our system.
+
+### Installing Composer
+
+For instructions on how to install Composer visit [getcomposer.org](https://getcomposer.org/download/).
+
+### Installing
+
+After cloning this repository, change into the newly created directory and run
+
+```bash
+composer install
+```
+
+or if you have installed Composer locally in your current directory
+
+```bash
+php composer.phar install
+```
+
+This will install all dependencies needed for the project.
+
+## Running the Tests
+
+All tests can be run by executing
+
+```bash
+vendor/bin/phpunit
+```
+
+`phpunit` will automatically find all tests inside the `test` directory and run them based on the configuration in the `phpunit.xml` file.
+
+### Testing Approach
+
+The test for the class `Greeting` verifies that the return value of the `sayHello` method returns the string "Hello {name}", where {name} is the value passed through to the constructor.
+
+## Running the Application
+
+PHP has an in-built server for local development. This can be started by executing
+
+```
+php -S localhost:8000 -t public
+```
+
+Then open your browser at `http://localhost:8000/example.php`
+
+You should see the text "Hello Ada Lovelace" on your screen.
+
+## Built With
+
+  - [PHP](https://secure.php.net/)
+  - [Composer](https://getcomposer.org/)
+  - [PHPUnit](https://phpunit.de/)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENCE.md](LICENCE.md) file for details.

composer.json

@@ -0,0 +1,22 @@
+{
+    "name": "elliotjreed/php-package-boilperplate",
+    "license": "MIT",
+    "type": "project",
+    "description": "Example PHP package.",
+    "autoload": {
+        "psr-4" : {
+            "Example\\" : "src/Example/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4" : {
+            "Tests\\Example\\" : "tests/Example/"
+        }
+    },
+    "require": {
+        "php": "^8.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.5"
+    }
+}

guide.md

@@ -0,0 +1,128 @@
+# PHP Package boilerplate project explanation
+
+PHP is a general-purpose server-side scripting language primarily used in web development. Originally created by Rasmus Lerdorf in 1994, it is now by The PHP Development Team.
+
+PHP originally stood for "Personal Home Page", but now stands for "PHP: Hypertext Preprocessor".
+
+## Further Material
+
+  - Homepage: [php.net](https://secure.php.net/)
+  - Documentation: [php.net/docs.php](https://secure.php.net/docs.php)
+  - PHP: The Right Way: [phptherightway.com](http://www.phptherightway.com/)
+  - Interactive PHP Tutorial: [learn-php.org](http://www.learn-php.org/)
+
+## Topics, Tools and Terms
+
+PHP packages were traditionally installed via PEAR (PHP Extension and Application Repository), but more recently the standard package and dependency management tool is Composer.
+
+Composer lets us run install commands to add packages to our system, for example `composer require phpunit` would add the unit testing framework PHPUnit to our system.
+
+For instructions on how to install Composer visit [getcomposer.org](https://getcomposer.org/download/).
+
+### Dependency Management
+
+Managing dependencies manually is time-consuming, fortunately Composer can automate this.
+
+We can list our dependencies in a `composer.json` file and run `composer install` to bring these into our project.
+
+An example `composer.json` file looks like this:
+
+```json
+{
+    "name": "example-project",
+    "require": {
+        "twig/twig": "^3.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^8.4"
+    }
+}
+```
+
+The "require" block tells Composer that the Twig templating package is required for production use and can install Twig with a version of 3.x.x (ie. up to, but not including, version 4).
+
+The "require-dev" block tells Composer that PHPUnit is required in development, but not in production.
+
+Dependencies can be added to `composer.json` by
+
+```bash
+composer require author/package-name
+```
+
+Development dependencies can be added by
+
+```bash
+composer require author/package-name --dev
+```
+
+Dependencies can be updated to their latest maximum version by running
+
+```bash
+composer update
+```
+
+Composer will also generate a `composer.lock` file on each `composer update` and the initial `composer install`. This is not meant to be edited directly, it tells Composer to use specific versions of packages - particularly useful when hyhou want your development dependencies to match what you will push to production.
+
+### Testing Tools
+
+There are a number of testing tools available for PHP. The most popular one is [PHPUnit](https://phpunit.de/). PHPUnit follows the classic xUnit approach.
+
+[Behat](http://behat.org/en/latest/) is the most popular behaviour-driven development (BDD) testing framework.
+
+[Codeception](http://codeception.com/) is a framework combining BDD, unit testing, and integration testing, and is cross-compatible with PHPUnit.
+
+In this guide we will be using PHPUnit as the testing framework.
+
+## Directory Structure
+
+A typical directory structure for a PHP project consists of a `src` directory that contains all source files and a `tests` directory that includes all tests. For web applications the publicly accessible files (eg. `index.php`) would reside in a `public` directory which would then be your webservers document root.
+
+Another common convention is having a `bin` directory that may contain executable files to start your application.
+
+  - src/
+  - test/
+  - public/
+  - composer.json
+  - composer.lock
+
+### Naming Conventions
+
+Directory names are in lower case. Class and interface files should be in upper case and match the class or interface names.
+Configuration, routes, and publicly accessible files should be in lower case.
+
+For example the class `Example` should be contained in file `Example.php`, the publicly accessible route to the application should be `index.php`.
+
+Tests match their production code file names with a `Test` suffix, e.g. tests for code in `src/Example.php` should be written in `test/ExampleTest.php`.
+
+## Example Project
+
+The main application consists of basically two files:
+
+- `public/example.php` is the main executable that instantiates and runs:
+  - `src/Example/Greeting.php` contains the main application.
+
+### Running the Tests
+
+All tests can be run by executing
+
+```bash
+vendor/phpunit/phpunit/phpunit
+```
+
+`phpunit` will automatically find all tests inside the `test` directory and run them based on the configuration in the `phpunit.xml` file.
+
+#### Testing Approach
+
+The test for the class `Greeting` verifies that the return value of the `sayHello` method returns the string "Hello {name}", where {name} is the value passed through to the constructor.
+
+### Running the Application
+
+PHP has an in-built server for local development. To run this change into the directory `public` and run
+
+```bash
+php -S localhost:8000
+```
+
+Then open your browser at `http://localhost:8000/example.php`
+
+You should see the text "Hello Ada Lovelace" being printed.

phpunit.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="vendor/autoload.php" backupGlobals="false" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd">
+  <coverage/>
+  <testsuites>
+    <testsuite name="Example">
+      <directory>./tests/Example/</directory>
+    </testsuite>
+  </testsuites>
+</phpunit>

public/example.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+require __DIR__ . '/../vendor/autoload.php';
+
+use Example\Greeting;
+
+$greeting = new Greeting('Ada Lovelace');
+
+echo $greeting->sayHello();

src/Example/Greeting.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Example;
+
+class Greeting
+{
+    public function __construct(private string $name = 'Stranger')
+    {
+    }
+
+    public function sayHello(): string
+    {
+        return 'Hello ' . $this->name;
+    }
+}

tests/Example/GreetingTest.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Tests\Example;
+
+use PHPUnit\Framework\TestCase;
+use Example\Greeting;
+
+class GreetingTest extends TestCase
+{
+    public function testItGreetsUser(): void
+    {
+        $greeting = new Greeting('Rasmus Lerdorf');
+
+        $this->assertSame('Hello Rasmus Lerdorf', $greeting->sayHello());
+    }
+}