HydePHP Site Builder GitHub Action

This GitHub Action builds and optionally deploys your HydePHP project.

Usage#

This action is available on the GitHub Marketplace, and can be used in a few ways depending on your needs.

Basic Usage#

Here is a quick sample workflow to get you started. It will automatically build your HydePHP site when you push to your repository, and then upload the compiled site as a workflow artifact.

1on: [push]
2 
3jobs:
4  build:
5    runs-on: ubuntu-latest
6    steps:
7      - uses: actions/checkout@v3
8      - uses: hydephp/action@master

Deployment options#

This action not only builds your site, but it can also deploy it for you. Here are the various deployment options supported by the action.

Artifact upload#

By default, the action will "deploy" your site by uploading it as a workflow artifact. This is useful if you want to customize the actual deployment process in a separate job, or if you just want to download the compiled files manually.

1- uses: hydephp/action@master
2  with:
3    deploy-to: artifact # This is already the default, but it's here for clarity.

You can also enable artifact uploading in addition to another deployment method with the upload-artifact input:

1- uses: hydephp/action@master
2  with:
3    deploy-to: pages
4    upload-artifact: true

GitHub Pages (Direct deployment)#

You can also deploy the compiled site directly to GitHub Pages, by setting the deploy-to input to "pages". This uses the official actions/deploy-pages action.

1- uses: hydephp/action@master
2  with:
3    deploy-to: "pages"

Please make sure that the GITHUB_TOKEN has the id-token: write and pages: write permissions.

You can set the permissions using the following code, added to the jobs.<job_id>.permissions section of your workflow file:

1build:
2  runs-on: ubuntu-latest
3  permissions:
4    contents: read
5    pages: write
6    id-token: write

You also need to make sure that your GitHub Pages source is set to "GitHub Actions". Simply follow the steps in the image below.

Supported repository structures#

The action works for both full HydePHP projects and "anonymous" projects containing only Markdown/Blade source files. The strategy used is automatically determined by the action, depending on the contents of the repository.

Both strategies require that the source files are located in the root directory of the repository. They both also support reading configuration from the hyde.yml file in the root directory.

Full HydePHP Projects#

The full HydePHP project strategy works by installing the project's composer dependencies.

This is the recommended setup for most projects, as allows you to use project directories, like additional Composer dependencies, the full configuration suite, custom code in the app directory, as well as custom views in the resources directory, and more.

This strategy is enabled when the project contains a composer.json file in the root directory.

Here is an example of a repository tree that would be built using this strategy:

 1├── _media
 2|── _pages
 3|── _posts
 4|── app
 5|── config
 6|── resources
 7|── composer.json
 8|── package.json
 9|── tailwind.config.js
10└── webpack.mix.js

You can also see this test repository where the tree was taken from: hyde-staging/github-action-test-project-1

Anonymous Projects#

The anonymous project strategy works by creating a new HydePHP project and then copying the source files into it. This is done when the project does not contain a composer.json file in the root directory. The installed project will use the latest stable version of HydePHP.

This strategy is great for simple projects that just contain basic pages and that don't require any additional dependencies. This documentation site, for example, is built using this strategy, and only contains a single docs/index.md file and a hyde.yml config file. The Torchlight syntax highlighting is enabled automatically by supplying the env-torchlight-token secret input.

Here is an example of a repository tree that would be built using this strategy:

1├── _media
2│   └── app.css
3├── _pages
4│   ├── 404.blade.php
5│   └── index.blade.php
6└── _posts
7    └── hello-world.md

You can also see this test repository where the tree was taken from: hyde-staging/github-action-test-project-2

Inputs#

debug#

Enables debug mode.

• Description: Enable debug mode.
• Required: false
• Default: "false"

deploy-to#

Specifies what to do with the compiled site. Options are: artifact or pages.

• Description: Specify what to do with the compiled site. Options are: artifact or pages.
• Required: true
• Default: "artifact"

upload-artifact#

Uploads the compiled site as an artifact. (In addition to the deployment method specified by deploy-to. Makes no change if deploy-to is already set to artifact.)

• Description: Upload the compiled site as an artifact.
• Required: false
• Default: "false"

framework-version#

Specifies the version of the HydePHP framework to use. If not specified, the latest stable version will be used.

This is only used when the anonymous project strategy is used, (i.e. when the project does not contain a composer.json file in the root directory).

• Description: Specify the version of HydePHP to use. If not specified, the latest stable version will be used.
• Required: false
• Default: "latest"

directory#

Specifies the directory containing the source files to build. This is useful if your source files are not located in the root directory of the repository.

• Description: Specify the directory containing the source files to build.
• Required: false
• Default: "."

config#

You can also specify configuration options using the config input. The lines in this input will be appended to the hyde.yml file in the root directory, allowing you to configure many parts of the Hyde project before the build.

• Description: List of lines to add to the hyde.yml config file
• Required: false
• Default: ""

Example:

1- uses: hydephp/action@config-array
2  with:
3    config: |
4      # Enter key-value Yaml here:
5      name: Example
6      url: ${{ github.deployment.url }}

See the HydePHP documentation for more information on the available configuration options and how to use the hyde.yml file.

Environment variables#

If your inputs contain sensitive information, you should use GitHub Secrets to store them.

You can also pass set the following inputs to be passed as environment variables for the build process:

env-site-name#

Sets the SITE_NAME environment variable

env-site-url#

Sets the SITE_URL environment variable

env-torchlight-token#

Sets the TORCHLIGHT_TOKEN environment variable