# 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: Run PHP-Prefixer
        uses: PHP-Prefixer/php-prefixer-build-action@v1.0.0
        with:
          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          project_id: ${{ secrets.PROJECT_ID }}
          token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
    # ... 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: Run PHP-Prefixer
        uses: PHP-Prefixer/php-prefixer-build-action@main
        with:
          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          project_id: ${{ secrets.PROJECT_ID }}
          token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

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 Action checks out your repository, packages, and submits the PHP Composer project to be prefixed, receives the processing results, and commits the results. By default, the Action processes the master or main branches and pushes the results into the prefixed branch. Alternatively, the ref parameter allows to process a different branch and commits the results to prefixed-ref.

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

# Step 1: Run the GitHub Action

Step 1: Run the GitHub Action

# Step 2: Wait for the PHP-Prefixer process

Step 2: Wait for the PHP-Prefixer process

# Step 3: The Action is completed

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`
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...`
SCHEMA	The PHP-Prefixer JSON configuration is applied to the project. By default, the prefixer uses the configuration present in composer.json. If there is no extra configuration or the extra configuration must be replaced, this parameter overrides the `composer.json` extra configuration to define the PHP-Prefixer schema.	No	`{"project-name": "Prefixed Project","namespaces-prefix": "PPP","global-scope-prefix": "PPP_"}`

The Action integrates the GitHub Action Checkout - actions/checkout (opens new window). The following parameters are also available:

    # Repository name with owner. For example, actions/checkout
    # Default: ${{ github.repository }}
    repository: ''

    # The branch, tag or SHA to checkout. When checking out the repository that
    # triggered a workflow, this defaults to the reference or SHA for that event.
    # Otherwise, uses the default branch.
    ref: ''

    # Personal access token (PAT) used to fetch the repository. The PAT is configured
    # with the local git config, which enables your scripts to run authenticated git
    # commands. The post-job step removes the PAT.
    #
    # We recommend using a service account with the least permissions necessary. Also
    # when generating a new PAT, select the least scopes necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    #
    # Default: ${{ github.token }}
    token: ''

    # SSH key used to fetch the repository. The SSH key is configured with the local
    # git config, which enables your scripts to run authenticated git commands. The
    # post-job step removes the SSH key.
    #
    # We recommend using a service account with the least permissions necessary.
    #
    # [Learn more about creating and using encrypted secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets)
    ssh-key: ''

    # Known hosts in addition to the user and global host key database. The public SSH
    # keys for a host may be obtained using the utility `ssh-keyscan`. For example,
    # `ssh-keyscan github.com`. The public key for github.com is always implicitly
    # added.
    ssh-known-hosts: ''

    # Whether to perform strict host key checking. When true, adds the options
    # `StrictHostKeyChecking=yes` and `CheckHostIP=no` to the SSH command line. Use
    # the input `ssh-known-hosts` to configure additional hosts.
    # Default: true
    ssh-strict: ''

    # Whether to download Git-LFS files
    # Default: false
    lfs: ''

    # Whether to checkout submodules: `true` to checkout submodules or `recursive` to
    # recursively checkout submodules.
    #
    # When the `ssh-key` input is not provided, SSH URLs beginning with
    # `git@github.com:` are converted to HTTPS.
    #
    # Default: false
    submodules: ''

# Prefixing Private Repositories

Follow these steps to prefix private repositories:

Step 1: Create a GitHub Personal Access Token (opens new window) for the Github account you wish to authenticate with.
Step 2: Next, add the GitHub Personal Access Token to your project using Github Secrets (opens new window), and pass it into the Action using the input.

Example yaml, showing how to pass secrets:

jobs:
  build:

    ...

      - name: Run PHP-Prefixer
        uses: PHP-Prefixer/php-prefixer-build-action@v1.0.0
        with:
          personal_access_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          project_id: ${{ secrets.PROJECT_ID }}
          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.

# Sample Projects

# 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 Tech Team at team@php-prefixer.com. We address all security vulnerabilities promptly.

# License

MIT (opens new window)

# Authors

PHP-Prefixer (opens new window), Desarrollos Inteligentes Virtuales, SL.

← Command-Line REST API →