README.md

%[packageName]%

%[description]%

Table of Contents

About
Installation
Examples
More
Changelog

^{If you like this project and would like to support its development, giving it a ⭐ would be appreciated!}

---

Post Fork

This repository is a template for PHP packages.

Placeholders

After forking this repository, some placeholders have to be replaced/updated with their corresponding values.

Available placeholders are:

• %[author]%: The name of the author (normally the same as GitHub username).
• %[authorName]%: The nice name of the author (capitalized name, as normally written).
• %[authorEmail]%: The email of the author.
• %[package]%: The name of the package (normally the same as GitHub repository name).
• %[packageName]%: The nice name of the package (capitalized version).
• %[year]%: The project year in YYYY format.
• %[description]%: The package description/summary.
• Package\Vendor namespace placeholder.

The regex for searching all placeholders is /(%\[(.+?)\]%|Vendor\\[\\]?Package)/ and for a specific placeholder /%\[placeholder\]%/ (or simply placeholder name). Simply use IDE Search & Replace feature to replace placeholders with their corresponding values.

NOTE: You wouldn't be able to run composer install until the placeholders in composer.json required to pass the schema check are replaced.

Contents

Build-Tools

This template is set up to use the following development tools:

• PHP-CS-Fixer (coding standard fixer)
• PHPStan (static analysis)
• PHPUnit (testing)
• PHPBench (benchmarking)
• Doctum (API documentation)

See composer.json "scripts" for more information.

CI/CD-Tools

This template is set up to use GitHub Actions as CI/CD Pipeline with the following tools:

• Composer (CI/CD)
• PHP-CS-Fixer (CI)
• PHPStan (CI)
• PHPUnit (CI)
• PHPBench (CI)
• Doctum (CD)
• Codecov (CI)
• Codacy (CI) [optional, disabled by default]

The Codecov and Codacy tools won't work until an account in the corresponding service is created and pointed to the repository.

The configuration files for these tools are already set up. Some extra configuration may be required as per project requirements.

Some small things still need to be taken care of:

1. Rename the directory .github/workflows.disabled to .github/workflows to enable GitHub Actions workflows (this done like this to prevent GitHub from running the workflows before the project is ready).
2. After the first successful run of the CI/CD workflows, enable GitHub Pages via Repository Settings. Set the "Source" as "Deploy from a branch", the "Branch" as gh-pages and the "Folder" as you like.
3. If you are not planning to use the provided Github Actions workflows. The generated API documentation will be created under build/doctum. Create an orphan branch named gh-pages and push the generated files to it then enabled GitHub pages for the repository.

Directory Structure

• .github/: GitHub specific configuration files. ^{(required; contains: workflows, templates for PRs/contributing/issue, funding, etc ...)}
• art/: This where you add visual assets that are related to the project (logos, demo images). ^{(optional; can be deleted)}
• bin/: This where you add scripts that are used in the project or should be provided for Composer. ^{(optional; can be deleted)}
• build/: This where build artifacts generated by development tools will be placed. ^{(optional; can be deleted, will be generated automatically)}
• docs/: This where you should add your project documentation (gh-pages branch is recommended). ^{(does not exist; only for reference)}
• dist/: This where you should add your project distribution files and packages. ^{(optional; can be deleted)}
• src/: This where you add your project source files. ^(required)
• tests/: This where you add your project tests and benchmarks. ^(required)
• vendor/: This where Composer dependencies will be installed. ^{(does not exist; only for reference)}
• /: The root directory of the project will contain other files like build tools configuration files, dependency manger files, documentation files, etc ...

Dummy Files

The template contains some dummy files that can be deleted if not needed. These files are listed below:

• bin/executable
• src/Main.php
• tests/Tests/MainTest.php
• tests/Benchmarks/MainBench.php
• **/*/.gitkeep

Finally

Adjust all files to you needs (Search & Replace, Edit or Delete), delete the "Post Fork" section from the README.md file and add some content to it. Finally commit the initial commit.

Add some glare to your README.md file using:

Hint: Here is some hint for you!

Fact: Here is some fact for you!

Note: Here is some note for you!

---

Key Features

1. One
2. Two
3. ...

---

About

Add a description here ...

---

Installation

Using Composer:

Install %[packageName]% through Composer using:

composer require %[author]%/%[package]%

---

Examples

Add some examples here ...

// add some code here

---

More

Add as many sections as needed ...

---

License

%[packageName]% is an open-source project licensed under the MIT license.
Copyright (c) %[year]% %[authorName]%. All rights reserved.