# GitHub Actions for PHP-Prefixer

In software engineering, CI/CD or CICD is the combined practice of continuous integration and delivery or deployment. CI/CD bridges the gaps between development and operation activities by enforcing automation in the building, testing, and deployment of applications.

To facilitate the usage of PHP-Prefixer, the Command-Line (opens new window) provides an ideal tool to integrate the prefixing service in any CI/CD context. As a reference implementation, we support the official GitHub Action for PHP-Prefixer.

# PHP Prefixer Build Action

GitHub Actions is a popular platform to automate software development workflows, like CI/CD built around the GitHub ecosystem.

You define your workflow using a YAML configuration file and store it in your Git repository. You can compose your automation with reusable building blocks called ‘Actions.’ Workflows are executed in containers for a repeatable and reliable process.

# Use the PHP Prefixer CLI in your Github Actions

The PHP Prefixer Build Action (opens new window) integrates the PHP-Prefixer (opens new window) service with GitHub Actions.

PHP Prefixer Build Action on GitHub Marketplace

PHP-Prefixer is a service to apply PHP prefixes to namespaces, functions, helpers, traits, interfaces, etc. You start with a Composer project and a set of dependencies and prefix all library files at once to generate a consistent prefixed codebase.

PHP-Prefixer abstracts the complexity of manually applying prefixes to PHP files. The service automates and streamlines the process of prefixing while providing the scalability and simplicity of serverless computing.

PHP-Prefixer is a rule-based expert system that processes the project and dependencies iteratively to prefix every project file.

Here is a sample class declaration:

namespace ACME\Carbon;

use ACME\Carbon\Exceptions\InvalidDateException;
use DateInterval;
use ACME\Symfony\Component\Translation;

class Carbon extends DateTime
{
    const NO_ZERO_DIFF = 01;
...

The associated prefixed class declaration, with a new and distinct namespace ACME:

namespace ACME\Carbon;

use ACME\Carbon\Exceptions\InvalidDateException;
use DateInterval;
use ACME\Symfony\Component\Translation;

class Carbon extends DateTime
{
    const NO_ZERO_DIFF = 01;
...

An example repository has been created at https://github.com/PHP-Prefixer/hello-wp-world to show how to use this Action in a real project. The repository depends on a private dependency and uses GitHub PAT/Personal Access Tokens for authentication.

To know more about the sample project, please, visit the original guide here: How to Prefix a WordPress Plugin (opens new window).

# Usage

To use the Action, you must create an account on PHP-Prefixer (opens new window) and prepare your projects with the prefix defined in the composer.json schema. You can first prefix your project on the service web interface and then integrate Action in your repositories. Before using the Action and the command-line, we recommend checking the documentation and guides here: https://php-prefixer.com/docs/guides/ (opens new window).

Create your Github Workflow configuration in .github/workflows/prefixer.yml.

name: Prefixer

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Run PHP-Prefixer
        uses: PHP-Prefixer/php-prefixer-build-action@v0.0.6
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          project_id: ${{ secrets.PROJECT_ID }}
    # ... then your own project steps ...

# Getting started with GitHub Actions for PHP-Prefixer

To illustrate how to use the new GitHub Action for PHP-Prefixer, we have updated the Hello Prefixed World (opens new window) plugin to automate the plugin prefixing.

The plugin makes a call to the PHP Prefixer Build Action (.github/workflow/prefix.yml) that integrates the service with GitHub Actions.

The complete workflow (opens new window) file is available in the sample plugin repository:

#
# Getting started with GitHub Actions for PHP-Prefixer
#
name: PHP-Prefixer

on: [workflow_dispatch]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Run PHP-Prefixer
        uses: PHP-Prefixer/php-prefixer-build-action@main
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          project_id: ${{ secrets.PROJECT_ID }}

Note that we reference two secrets in this configuration. One is for the PHP-Prefixer Personal Access Token to authenticate, and the second is for the Project ID to integrate with your configured project.

Reference to two secrets

The Personal Access Token and the Project ID are parameters that must be configured on your PHP-Prefixer account. The new settings must be configured on Github Secrets (opens new window).

# Running PHP Prefixer Build Action

The Action is a straightforward implementation of the PHP-Prefixer CLI (opens new window). The Action clones the repository, packages the project in a ZIP file, sends the source code to PHP-Prefixer, and receives the results. The new package is then committed to the prefixed branch to make it available at the repository level.

The sample Action is configured on the sample plugin repository that you can run manually.

Step 1: Run the GitHub Action

Step 2: Wait for the PHP-Prefixer process

Step 3: The Action is completed, and the results are committed to the prefixed branch

In this sample, we can see how the GitHub Action runs and processes the output that the user receives on the screen. It might take a few iterations to fix syntax and get everything right, but a successful prefixed project is an outcome. The results can be checked in the WordPress plugin prefixed branch: https://github.com/PHP-Prefixer/hello-wp-world/tree/prefixed (opens new window).

# Available Parameters

The Action requires two parameters to function, and it can receive additional parameters for GitHub integration:

Parameter Description Required Example
PERSONAL_ACCESS_TOKEN The PHP-Prefixer PAT/Personal Access Token. The token must be configured in the PHP-Prefixer account. Yes 789\|123456789...
PROJECT_ID The project ID to process the source code. The project must be configured in your account in the PHP-Prefixer account. Yes 5432
SOURCE_DIR_PATH The relative path to the source project directory. It must contain a .git repository and composer.json file. If not, the base repository directory will be used as the value. Example: foo/bar. No ./
TARGET_BRANCH The branch in the repository where PHP-Prefixer will store the prefixed files after processing. Default value: prefixed. No
GH_PERSONAL_ACCESS_TOKEN The GitHub PAT/Personal Access Token to access private repositories. It is only required if the project, the library or the dependencies are private. No ghp_F4fZ9Cq7QF...

# Prefixing Private Repositories

Follow these steps to prefix private repositories:

Example yaml, showing how to pass secrets:

jobs:
  build:

    ...

      - name: Run PHP-Prefixer
        uses: PHP-Prefixer/php-prefixer-build-action@v0.0.6
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          project_id: ${{ secrets.PROJECT_ID }}
          gh_personal_access_token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

There is an example repository available for reference at https://github.com/PHP-Prefixer/hello-wp-world (opens new window) that uses a private dependency. Check it out for a live project.

# Contributing

The current Action is a starting point to prefix PHP code. If you want to improve the current command-line, contributions are always welcome!

# Security

If you discover a security vulnerability within this package, please email Anibal Sanchez at team@php-prefixer.com. We address all security vulnerabilities promptly.

# License

MIT (opens new window)

# Authors