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.

env

You can set arbitrary environment variables using the env input. Simply provide each variable in KEY=VALUE format, one per line:

1- uses: hydephp/action@master
2  with:
3    deploy-to: "pages"
4    env: |
5      SITE_NAME=My Site
6      SITE_URL=https://example.com
7      TORCHLIGHT_TOKEN=${{ secrets.TORCHLIGHT_TOKEN }}

The environment variables will be available during the build process. Note that if you're using sensitive information, you should use GitHub Secrets instead of hardcoding the values. Also make sure your input is valid "dotenv" syntax.

Deprecated inputs

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

env-site-name

[!WARNING] Deprecated: Use the env input instead with SITE_NAME=value

Sets the SITE_NAME environment variable

env-site-url

[!WARNING] Deprecated: Use the env input instead with SITE_URL=value

Sets the SITE_URL environment variable

env-torchlight-token

[!WARNING] Deprecated: Use the env input instead with TORCHLIGHT_TOKEN=value

Sets the TORCHLIGHT_TOKEN environment variable

Site URLs

It's highly recommended to set the site URL for your project so that sitemaps and meta tags are generated correctly.

You can do this by setting the SITE_URL environment variable, or by adding the url key to your hyde.yml file or config/hyde.php file.

If the site URL is not set, the action will output a warning and suggest a solution. An easy way to set the site URL is to use the env input as seen above.