diff --git a/.distignore b/.distignore index 9989522..e36c6bb 100644 --- a/.distignore +++ b/.distignore @@ -1,28 +1,97 @@ -# Files left out of the WordPress.org / release build +# Files and folders left out of the release zip and the deploys. +# Patterns use rsync/.gitignore syntax; a leading "/" anchors to the repo root. +# Anything NOT listed here is "deployable": changing it triggers a release. + +# GitHub, CI and repo setup +/.github +/bin +/.wordpress-org + +# Git .git -.github .gitignore +.gitattributes .distignore -.editorconfig -.claude -.wp-env.json -.wp-env.override.json -.DS_Store -Thumbs.db -README.md + +# IDE / editors / AI assistants +.vscode +.vscodeignore +.idea +sftp.json +/.claude +CLAUDE.md + +# Docker (local development) +/.docker +Dockerfile +docker-compose.yml + +# Environment +.env +.env.example + +# Composer (dev tools only; the plugin does not need vendor/) +/vendor composer.json composer.lock + +# Node / front-end tooling +node_modules package.json package-lock.json +.nvmrc +.eslintrc +.eslintcache +.prettierrc +.stylelintrc +.stylelintcache + +# Coding standards / static analysis +.editorconfig phpcs.xml phpcs.xml.dist -.phpcs.xml.dist +.phpcs.cache +phpcs-report.xml +phpstan.neon +phpstan.neon.dist + +# Testing +/tests phpunit.xml phpunit.xml.dist -node_modules -tests -bin -*.map +phpunit-integration.xml.dist +.wp-env.json +.wp-env.override.json +.phpunit.result.cache +.phpunit.cache + +# Block sources: `npm run build` compiles them into build/, which ships +# StackFolio: blocks/ is NOT excluded. The block is plain JavaScript with no +# build step, so blocks/album-grid/ is the runtime code and must ship. +# /blocks + +# Build output +/release *.zip -*.tar.gz + +# OS files +.DS_Store +Thumbs.db + +# Logs and database dumps *.log +*.sql +*.sqlite + +# Documentation only needed on GitHub (readme.txt ships) +README.md +CODE_OF_CONDUCT.md +CONTRIBUTING.md +SECURITY.md + +# -------------------------------------------------- +# Project-specific (kept from this repo) +# -------------------------------------------------- +.phpcs.xml.dist +*.map +*.tar.gz diff --git a/.docker/uploads.ini b/.docker/uploads.ini new file mode 100644 index 0000000..ae9e5b0 --- /dev/null +++ b/.docker/uploads.ini @@ -0,0 +1,5 @@ +upload_max_filesize = 64M +post_max_size = 64M +memory_limit = 512M +max_execution_time = 300 +max_input_vars = 3000 diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..d7baa4d --- /dev/null +++ b/.env.example @@ -0,0 +1,15 @@ +WORDPRESS_DB_HOST=db +WORDPRESS_DB_USER=wordpress +WORDPRESS_DB_PASSWORD=wordpress +WORDPRESS_DB_NAME=wordpress + +MYSQL_ROOT_PASSWORD=root +MYSQL_DATABASE=wordpress +MYSQL_USER=wordpress +MYSQL_PASSWORD=wordpress + +PLUGIN_SLUG=stackfolio + +# Host ports (change these if another project already uses them) +WP_HTTP_PORT=8000 +PMA_HTTP_PORT=8080 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..8f67515 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,39 @@ +name: Bug report +description: Something doesn't work as it should. +labels: [bug] +body: + - type: textarea + id: what + attributes: + label: What happened? + description: What did you do, what did you expect, and what happened instead? + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + placeholder: | + 1. Go to ... + 2. Click ... + 3. See error ... + validations: + required: true + - type: input + id: version + attributes: + label: Plugin version + placeholder: e.g. 2.1.0 + validations: + required: true + - type: input + id: environment + attributes: + label: WordPress and PHP versions + placeholder: e.g. WordPress 7.0, PHP 8.3 + - type: textarea + id: logs + attributes: + label: Errors or logs + description: PHP errors (wp-content/debug.log) or browser console errors, if any. + render: text diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..6612811 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: true +contact_links: + - name: Report a security vulnerability + url: https://github.com/wpgenius/stackfolio/security/advisories/new + about: Please report security issues privately, not as a public issue. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..866dc47 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,21 @@ +name: Feature or change +description: Suggest an improvement or a new feature. +labels: [enhancement] +body: + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Who needs it, and what do they do today without it? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: What would you like to happen? + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives you considered diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..460f186 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,41 @@ +version: 2 +updates: + # Keeps the SHA-pinned actions in .github/workflows up to date. + # Dependabot PRs need no linked issue; none of these change the plugin zip + # unless build/ changes, so they normally make no release. + - package-ecosystem: github-actions + directory: / + schedule: + interval: monthly + commit-message: + prefix: ci + labels: + - dependencies + + # Dev tools from package.json (@wordpress/scripts and friends), one grouped + # PR a month. If CI then says build/ is out of date, check out the PR's + # branch, run `npm run build`, and commit the result to it. + - package-ecosystem: npm + directory: / + schedule: + interval: monthly + groups: + npm: + patterns: ['*'] + commit-message: + prefix: build + labels: + - dependencies + + # Dev tools from composer.json (PHPCS, PHPStan, PHPUnit), one grouped PR a month. + - package-ecosystem: composer + directory: / + schedule: + interval: monthly + groups: + composer: + patterns: ['*'] + commit-message: + prefix: build + labels: + - dependencies diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..12e9f5b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,20 @@ + +Closes # + +## What changed + + + +## How it was tested + +- [ ] `composer lint`, `composer phpcs`, `composer phpstan` and `composer test` pass +- [ ] `npm run lint` passes (and `npm run build` was run and committed after block changes) +- [ ] Tried in WordPress (or covered by `npm run test:integration`) + + diff --git a/.github/scripts/lib.sh b/.github/scripts/lib.sh new file mode 100755 index 0000000..93e356e --- /dev/null +++ b/.github/scripts/lib.sh @@ -0,0 +1,84 @@ +#!/usr/bin/env bash +# Shared helpers for the release and deploy workflows. Source, don't execute. + +# File that holds the version header, in the repo root: +# plugin: the PHP file with a "Plugin Name:" header +# theme: style.css with a "Theme Name:" header +main_plugin_file() { + local f + for f in *.php; do + [ -f "$f" ] || continue + if head -n 30 "$f" | grep -qiE '^[[:space:]/*#@]*Plugin Name:'; then + echo "$f" + return 0 + fi + done + if [ -f style.css ] && head -n 30 style.css | grep -qiE '^[[:space:]/*#@]*Theme Name:'; then + echo "style.css" + return 0 + fi + echo "::error::No plugin file ('Plugin Name:' header in a root .php file) or theme stylesheet ('Theme Name:' header in style.css) found in the repo root" >&2 + return 1 +} + +# Version from the main plugin file header. +header_version() { + head -n 30 "$1" | sed -nE 's/^[[:space:]/*#@]*Version:[[:space:]]*([^[:space:]]+).*/\1/Ip' | head -n 1 +} + +# Reads paths on stdin, prints the ones that ship (not excluded by .distignore). +# .distignore uses .gitignore syntax, so git itself does the matching in a +# scratch repo whose only ignore file is a copy of .distignore. +deployable_paths() { + local scratch + scratch=$(mktemp -d) + git init -q "$scratch" + cp .distignore "$scratch/.gitignore" + printf '.git\n' >> "$scratch/.gitignore" + local paths ignored + paths=$(cat) + [ -n "$paths" ] || { rm -rf "$scratch"; return 0; } + ignored=$(cd "$scratch" && printf '%s\n' "$paths" | git check-ignore --no-index --stdin || true) + rm -rf "$scratch" + printf '%s\n' "$paths" | while IFS= read -r p; do + [ -n "$p" ] || continue + if ! printf '%s\n' "$ignored" | grep -qxF -- "$p"; then + echo "$p" + fi + done +} + +# Copies the deployable files into $1 (created if missing). +build_package() { + local dest="$1" + mkdir -p "$dest" + rsync --archive --delete --exclude='.git' --exclude-from='.distignore' ./ "$dest/" + if find "$dest" -type l | grep -q .; then + echo "::error::Symlinks are not allowed in the package:" >&2 + find "$dest" -type l >&2 + return 1 + fi +} + +# Builds the package as it is at a git revision, from committed files only +# (untracked vendor/, node_modules/ etc. never count), using that revision's +# own .distignore. Usage: package_at +package_at() { + local rev="$1" dest="$2" tree + tree=$(mktemp -d) + git archive --format=tar "$rev" | tar -x -C "$tree" + ( cd "$tree" && touch .distignore && build_package "$dest" ) + rm -rf "$tree" +} + +# Prints the files that differ between the packages at two revisions +# (added, removed or changed); prints nothing when the zips would be identical. +# Usage: package_diff +package_diff() { + local work + work=$(mktemp -d) + package_at "$1" "$work/old" + package_at "$2" "$work/new" + ( cd "$work" && diff -rq old new || true ) | sed -E 's#^Files old/(.*) and new/.* differ$#changed \1#; s#^Only in old(/?)(.*): (.*)$#removed \2/\3#; s#^Only in new(/?)(.*): (.*)$#added \2/\3#; s# /# #' + rm -rf "$work" +} \ No newline at end of file diff --git a/.github/scripts/release-plan.sh b/.github/scripts/release-plan.sh new file mode 100755 index 0000000..39a39bc --- /dev/null +++ b/.github/scripts/release-plan.sh @@ -0,0 +1,140 @@ +#!/usr/bin/env bash +# Decides whether main needs a release and, if so, which version and changelog. +# +# Output (key=value lines, appended to $GITHUB_OUTPUT when set): +# release=true|false version=X.Y.Z tag=vX.Y.Z +# The changelog (one "* line" per change) is written to $CHANGELOG_FILE. +# +# Rules: +# - Only strict vMAJOR.MINOR.PATCH tags count as previous releases. +# - A release happens only when the plugin zip would change: the package built +# at the last release tag is compared with the one built at HEAD (each with +# its own .distignore). Docs, CI, config and .distignore-only edits that +# leave the zip identical make no release. +# - The changelog lists the commits that touched a deployable file (anything +# .distignore does not exclude). +# - Bump: patch, or minor/major when a released PR has the label +# release:minor / release:major (the highest wins). +# - Changelog: the titles of the issues closed by the released PRs; a commit +# without a PR or linked issue contributes its subject line instead. +# - No previous release: version = the plugin header Version (or 1.0.0), +# changelog "Initial release." +# +# Needs: git with full history and tags, gh (GH_TOKEN), GITHUB_REPOSITORY. +set -euo pipefail + +here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +# shellcheck source=lib.sh +. "$here/lib.sh" + +: "${GITHUB_REPOSITORY:?GITHUB_REPOSITORY must be set (owner/repo)}" +CHANGELOG_FILE=${CHANGELOG_FILE:-changelog.txt} +out() { echo "$1"; if [ -n "${GITHUB_OUTPUT:-}" ]; then echo "$1" >> "$GITHUB_OUTPUT"; fi; } + +semver='^v[0-9]+\.[0-9]+\.[0-9]+$' +last=$(git tag --list 'v*' --merged HEAD --sort=-v:refname | grep -E "$semver" | head -n 1 || true) +main_file=$(main_plugin_file) + +if [ -z "$last" ]; then + version=$(header_version "$main_file") + [[ "v$version" =~ $semver ]] || version=1.0.0 + echo "No previous release; first release will be $version." + printf '* Initial release.\n' > "$CHANGELOG_FILE" + out "release=true" + out "version=$version" + out "tag=v$version" + exit 0 +fi + +echo "Last release: $last" + +changes=$(package_diff "$last" HEAD) +if [ -z "$changes" ]; then + echo "The plugin package is identical to $last: no release." + out "release=false" + exit 0 +fi +echo "Package changes since $last:" +printf '%s\n' "$changes" | sed 's/^/ /' + +# A failed GitHub call must stop the release: guessing would turn a major +# release into a patch, or drop changelog lines. Nothing is pushed before this +# point, so the run can simply be started again. +api_failed() { + echo "::error::Could not read $1 from GitHub. Nothing was released; re-run this workflow." >&2 + exit 1 +} + +bump=patch +seen_issues=" " # issue numbers already in the changelog, space separated +: > "$CHANGELOG_FILE" +deployable_commits=0 +distignore_commits="" # commits that only changed .distignore (used if nothing else explains the change) + +# Oldest first, so the changelog reads in merge order. +for sha in $(git rev-list --reverse --no-merges "$last"..HEAD); do + changed=$(git diff-tree --no-commit-id --name-only -r "$sha") + shipped=$(printf '%s\n' "$changed" | deployable_paths) + subject=$(git log -1 --format=%s "$sha") + if [ -z "$shipped" ]; then + if grep -qx '.distignore' <<<"$changed"; then + distignore_commits+="* $subject"$'\n' + fi + echo " skip ${sha:0:7} $subject (no deployable files)" + continue + fi + echo " ship ${sha:0:7} $subject" + deployable_commits=$((deployable_commits + 1)) + + pr=$(gh api "repos/$GITHUB_REPOSITORY/commits/$sha/pulls" --jq '.[0].number // empty') \ + || api_failed "the pull request of commit ${sha:0:7}" + lines="" + if [ -n "$pr" ]; then + labels=$(gh api "repos/$GITHUB_REPOSITORY/issues/$pr/labels" --jq '.[].name') \ + || api_failed "the labels of PR #$pr" + if grep -qx 'release:major' <<<"$labels"; then bump=major + elif grep -qx 'release:minor' <<<"$labels" && [ "$bump" != major ]; then bump=minor + fi + # Issues this PR closed: "numbertitle" per line. + issues=$(gh api graphql -F owner="${GITHUB_REPOSITORY%/*}" -F name="${GITHUB_REPOSITORY#*/}" -F pr="$pr" -f query=' + query($owner: String!, $name: String!, $pr: Int!) { + repository(owner: $owner, name: $name) { + pullRequest(number: $pr) { + closingIssuesReferences(first: 50) { nodes { number title } } + } + } + }' --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[] | "\(.number)\t\(.title)"') \ + || api_failed "the issues closed by PR #$pr" + while IFS=$'\t' read -r num title; do + [ -n "$num" ] || continue + case "$seen_issues" in *" $num "*) continue ;; esac + seen_issues+="$num " + lines+="* $title (#$num)"$'\n' + done <<<"$issues" + fi + if [ -z "$lines" ]; then + # Squash commits end with " (#PR)"; keep the subject as written. + lines="* $subject"$'\n' + fi + printf '%s' "$lines" >> "$CHANGELOG_FILE" +done + +if [ "$deployable_commits" -eq 0 ]; then + # The zip changed only through .distignore (a file now ships or no longer does). + if [ -n "$distignore_commits" ]; then + printf '%s' "$distignore_commits" > "$CHANGELOG_FILE" + else + printf '* Maintenance release.\n' > "$CHANGELOG_FILE" + fi +fi + +IFS=. read -r major minor patch <<<"${last#v}" +case "$bump" in + major) version="$((major + 1)).0.0" ;; + minor) version="$major.$((minor + 1)).0" ;; + *) version="$major.$minor.$((patch + 1))" ;; +esac +echo "Bump: $bump -> $version" +out "release=true" +out "version=$version" +out "tag=v$version" diff --git a/.github/scripts/stamp-version.sh b/.github/scripts/stamp-version.sh new file mode 100755 index 0000000..6680e22 --- /dev/null +++ b/.github/scripts/stamp-version.sh @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +# Writes a release into the plugin or theme files: +# - "Version:" in the main plugin file header (style.css for a theme), +# and a *_VERSION constant there, if one is defined +# - "Stable tag:" in readme.txt, when it has one (themes do not) +# - a new "= X.Y.Z =" entry at the top of readme.txt's "== Changelog ==" +# Usage: stamp-version.sh +set -euo pipefail + +here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd) +# shellcheck source=lib.sh +. "$here/lib.sh" + +version=${1:?version required} +notes=${2:?changelog file required} +[[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::bad version $version" >&2; exit 1; } +[ -s "$notes" ] || { echo "::error::changelog file $notes is empty" >&2; exit 1; } + +main_file=$(main_plugin_file) + +# Header Version: only the first match, only within the header block. +VERSION="$version" perl -0pi -e 's/^([ \t\/*#@]*Version:[ \t]*)\S+/${1}$ENV{VERSION}/mi' "$main_file" +[ "$(header_version "$main_file")" = "$version" ] || { echo "::error::could not set Version in $main_file" >&2; exit 1; } + +# Optional version constant, e.g. define( 'MYPLUGIN_VERSION', '1.2.3' ); +VERSION="$version" perl -pi -e "s/(define\(\s*'[A-Z0-9_]+_VERSION'\s*,\s*')[^']*(')/\${1}\$ENV{VERSION}\${2}/" "$main_file" + +if [ -f readme.txt ]; then + if grep -qiE '^Stable tag:' readme.txt; then + VERSION="$version" perl -pi -e 's/^(Stable tag:[ \t]*)\S+/${1}$ENV{VERSION}/i' readme.txt + grep -qiE "^Stable tag:[[:space:]]*$version\$" readme.txt || { echo "::error::could not set Stable tag in readme.txt" >&2; exit 1; } + else + # Theme readmes have no Stable tag; their version lives in style.css. + echo "::notice::readme.txt has no 'Stable tag:' line; skipped" + fi + + if grep -q '^== Changelog ==' readme.txt; then + entry=$(printf '= %s =\n\n%s' "$version" "$(cat "$notes")") + ENTRY="$entry" perl -0pi -e 's/^(== Changelog ==[ \t]*\n)\n*/$1\n$ENV{ENTRY}\n\n/m' readme.txt + else + echo "::warning::readme.txt has no '== Changelog ==' section; changelog not written" + fi +fi + +echo "Stamped $version into $main_file and readme.txt" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..51895c0 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,144 @@ +name: CI + +# Checks every pull request (and pushes to main): PHPStan static analysis, +# PHP syntax and unit tests on each supported PHP version, WordPress Coding +# Standards, JS/CSS lint, and the official WordPress Plugin Check on the plugin +# as it ships (the release zip). +# +# StackFolio: adapted from the standard. The block is plain JavaScript with no +# build step, so there is no block-build check, and there are no integration +# tests or rename script yet, so those jobs are left out. +# +# The last job, "CI", passes only when every other job passed. It is the one +# check the "Protect main" ruleset requires (bin/setup-github.sh), so jobs can +# be added or renamed here without touching the ruleset. + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + php-lint: + name: PHP ${{ matrix.php }} syntax and tests + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + # Keep the lowest version in sync with "Requires PHP" in the plugin header. + php: ['7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5'] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 + with: + php-version: ${{ matrix.php }} + coverage: none + tools: composer + + - run: composer install --no-interaction --no-progress + + - run: composer lint + + - run: composer test + + phpcs: + name: Coding standards (PHPCS) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 + with: + php-version: '8.3' + coverage: none + tools: composer, cs2pr + + - run: composer install --no-interaction --no-progress + + - name: Run PHPCS (annotates the PR diff) + run: vendor/bin/phpcs -q --report-full --report-checkstyle=./phpcs-report.xml || (cs2pr ./phpcs-report.xml && exit 1) + + phpstan: + name: Static analysis (PHPStan) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - uses: shivammathur/setup-php@eb7c497e18156a6bbabfef1d3a82760b9eda3962 # 2.40.0 + with: + php-version: '8.3' + coverage: none + tools: composer + + - run: composer install --no-interaction --no-progress + + - run: composer phpstan -- --no-progress --error-format=github + + js-css-lint: + name: JS/CSS lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version-file: .nvmrc + cache: npm + + - run: npm ci + + - run: npm run lint + + + plugin-check: + name: Plugin Check + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Build the plugin as it ships + id: package + run: | + set -euo pipefail + . .github/scripts/lib.sh + slug="${{ vars.PLUGIN_SLUG }}" + slug="${slug:-${GITHUB_REPOSITORY#*/}}" + build_package "$RUNNER_TEMP/package/$slug" + echo "dir=$RUNNER_TEMP/package/$slug" >> "$GITHUB_OUTPUT" + echo "slug=$slug" >> "$GITHUB_OUTPUT" + + # The checks WordPress.org runs when reviewing a plugin. Errors fail the + # job; warnings are shown as annotations on the PR. + - uses: WordPress/plugin-check-action@10857da14b6c2246d15402b3e69f777edcf8c12e # v1.1.9 + with: + build-dir: ${{ steps.package.outputs.dir }} + slug: ${{ steps.package.outputs.slug }} + + + ci: + name: CI + # Runs even when a job above failed, so the required check always reports. + if: always() + needs: [php-lint, phpcs, phpstan, js-css-lint, plugin-check] + runs-on: ubuntu-latest + steps: + - name: All jobs passed + env: + RESULTS: ${{ join(needs.*.result, ' ') }} + run: | + echo "Job results: $RESULTS" + for result in $RESULTS; do + if [ "$result" != success ]; then + echo "::error::A CI job did not pass ($result)." + exit 1 + fi + done diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..7569e02 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,257 @@ +name: Deploy + +# Uploads a released version (the files .distignore keeps) to one target. +# Runs automatically after each release only while the repo variable +# DEPLOY_ENABLED is 'true' (off by default). A manual run checks the +# connection; it uploads only when DEPLOY_ENABLED is 'true' and "deploy" is ticked. +# +# DEPLOY_METHOD (repo variable) picks the target: +# +# ftps FTP with TLS forced. Never deletes remote files. +# vars: FTP_PORT (21), FTP_REMOTE_PATH (/), FTP_SSL_VERIFY (true) +# secrets: FTP_HOST, FTP_USERNAME, FTP_PASSWORD +# +# ssh rsync over SSH with a deploy key. +# vars: SSH_PORT (22), SSH_REMOTE_PATH (required), +# SSH_DELETE ('true' removes remote files that are no longer shipped) +# secrets: SSH_HOST, SSH_USER, SSH_PRIVATE_KEY, +# SSH_KNOWN_HOSTS (output of `ssh-keyscan -p PORT HOST`) +# +# wporg WordPress.org plugin SVN: trunk/, tags/X.Y.Z/ and assets/ +# (assets come from .wordpress-org/ in this repo, if present). +# vars: WPORG_SLUG (defaults to PLUGIN_SLUG, then the repo name) +# secrets: SVN_USERNAME, SVN_PASSWORD +# +# Secrets are masked in logs. Runs in the "production" environment, so you can +# add required reviewers there for an extra approval step. + +on: + workflow_call: + inputs: + tag: + description: Release tag to deploy (vX.Y.Z). + required: true + type: string + deploy: + description: Upload after the checks. + required: false + default: true + type: boolean + workflow_dispatch: + inputs: + tag: + description: Release tag to deploy (empty = latest release). + required: false + default: '' + type: string + deploy: + description: Upload after the connection check (also needs DEPLOY_ENABLED=true). + required: true + default: false + type: boolean + +permissions: + contents: read + +concurrency: + group: deploy-production + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + environment: production + env: + GH_TOKEN: ${{ github.token }} + DEPLOY_METHOD: ${{ vars.DEPLOY_METHOD }} + UPLOAD: ${{ vars.DEPLOY_ENABLED == 'true' && inputs.deploy }} + steps: + - name: Resolve release tag + id: tag + env: + INPUT_TAG: ${{ inputs.tag }} + run: | + set -euo pipefail + tag="$INPUT_TAG" + if [ -z "$tag" ]; then + tag=$(gh release view --repo "$GITHUB_REPOSITORY" --json tagName --jq .tagName) + fi + [[ "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::bad tag '$tag'"; exit 1; } + echo "tag=$tag" >> "$GITHUB_OUTPUT" + echo "version=${tag#v}" >> "$GITHUB_OUTPUT" + echo "Deploying $tag with method '${DEPLOY_METHOD:-unset}' (upload: $UPLOAD)" + + - name: Check out the released commit + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ steps.tag.outputs.tag }} + + - name: Build package + id: pkg + run: | + set -euo pipefail + . .github/scripts/lib.sh + dir="$RUNNER_TEMP/package" + build_package "$dir" + test -f "$dir/$(main_plugin_file)" + echo "dir=$dir" >> "$GITHUB_OUTPUT" + (cd "$dir" && find . -type f | sort) + + - name: Check deploy method + run: | + case "$DEPLOY_METHOD" in + ftps|ssh|wporg) ;; + *) echo "::error::Set the repo variable DEPLOY_METHOD to ftps, ssh or wporg (now: '${DEPLOY_METHOD}')"; exit 1 ;; + esac + + # ---------------------------------------------------------------- FTPS + - name: FTPS - check settings and connection + if: env.DEPLOY_METHOD == 'ftps' + env: + FTP_HOST: ${{ secrets.FTP_HOST }} + FTP_USERNAME: ${{ secrets.FTP_USERNAME }} + FTP_PASSWORD: ${{ secrets.FTP_PASSWORD }} + FTP_PORT: ${{ vars.FTP_PORT || '21' }} + FTP_REMOTE_PATH: ${{ vars.FTP_REMOTE_PATH || '/' }} + FTP_SSL_VERIFY: ${{ vars.FTP_SSL_VERIFY || 'true' }} + run: | + set -euo pipefail + bad=0 + for n in FTP_HOST FTP_USERNAME FTP_PASSWORD; do [ -n "${!n}" ] || { echo "::error::$n is not set"; bad=1; }; done + # These are interpolated into lftp commands: accept only safe shapes. + [[ "$FTP_HOST" =~ ^[A-Za-z0-9.-]+$ ]] || { echo "::error::FTP_HOST must be a plain hostname"; bad=1; } + [[ "$FTP_PORT" =~ ^[0-9]{1,5}$ ]] || { echo "::error::FTP_PORT must be a number"; bad=1; } + [[ "$FTP_REMOTE_PATH" =~ ^/[A-Za-z0-9._/-]*$ ]] || { echo "::error::FTP_REMOTE_PATH must be an absolute path of letters, digits, . _ - /"; bad=1; } + [[ "$FTP_SSL_VERIFY" =~ ^(true|false)$ ]] || { echo "::error::FTP_SSL_VERIFY must be true or false"; bad=1; } + [ "$bad" -eq 0 ] || exit 1 + [ "$FTP_SSL_VERIFY" = true ] || echo "::warning::FTP_SSL_VERIFY=false: the server certificate is not verified" + sudo apt-get update -qq && sudo apt-get install -y -qq lftp >/dev/null + LFTP_PASSWORD="$FTP_PASSWORD" lftp --env-password -u "$FTP_USERNAME" "ftp://$FTP_HOST:$FTP_PORT" < ~/.ssh/deploy_key && chmod 600 ~/.ssh/deploy_key + printf '%s\n' "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts && chmod 600 ~/.ssh/known_hosts + ssh -i ~/.ssh/deploy_key -p "$SSH_PORT" -o BatchMode=yes -o StrictHostKeyChecking=yes \ + "$SSH_USER@$SSH_HOST" "test -d \"\$(dirname '$SSH_REMOTE_PATH')\" && echo connected" + + - name: SSH - upload + if: env.DEPLOY_METHOD == 'ssh' && env.UPLOAD == 'true' + env: + SSH_HOST: ${{ secrets.SSH_HOST }} + SSH_USER: ${{ secrets.SSH_USER }} + SSH_PORT: ${{ vars.SSH_PORT || '22' }} + SSH_REMOTE_PATH: ${{ vars.SSH_REMOTE_PATH }} + SSH_DELETE: ${{ vars.SSH_DELETE || 'false' }} + PKG: ${{ steps.pkg.outputs.dir }} + run: | + set -euo pipefail + delete=() + [ "$SSH_DELETE" = true ] && delete=(--delete) + rsync -rlz --checksum --itemize-changes "${delete[@]}" \ + -e "ssh -i $HOME/.ssh/deploy_key -p $SSH_PORT -o BatchMode=yes -o StrictHostKeyChecking=yes" \ + --rsync-path="mkdir -p '$SSH_REMOTE_PATH' && rsync" \ + "$PKG/" "$SSH_USER@$SSH_HOST:$SSH_REMOTE_PATH/" + + # ----------------------------------------------------- WordPress.org SVN + - name: WordPress.org - check settings and SVN access + if: env.DEPLOY_METHOD == 'wporg' + id: wporg + env: + SVN_USERNAME: ${{ secrets.SVN_USERNAME }} + SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }} + WPORG_SLUG: ${{ vars.WPORG_SLUG || vars.PLUGIN_SLUG }} + run: | + set -euo pipefail + slug="${WPORG_SLUG:-${GITHUB_REPOSITORY#*/}}" + bad=0 + for n in SVN_USERNAME SVN_PASSWORD; do [ -n "${!n}" ] || { echo "::error::$n is not set"; bad=1; }; done + [[ "$slug" =~ ^[a-z0-9][a-z0-9-]*$ ]] || { echo "::error::bad WordPress.org slug '$slug'"; bad=1; } + [ "$bad" -eq 0 ] || exit 1 + sudo apt-get update -qq && sudo apt-get install -y -qq subversion >/dev/null + url="https://plugins.svn.wordpress.org/$slug" + svn ls "$url" --non-interactive >/dev/null || { echo "::error::$url is not reachable (is the plugin approved on WordPress.org?)"; exit 1; } + echo "url=$url" >> "$GITHUB_OUTPUT" + + - name: WordPress.org - commit trunk, tag and assets + if: env.DEPLOY_METHOD == 'wporg' && env.UPLOAD == 'true' + env: + SVN_USERNAME: ${{ secrets.SVN_USERNAME }} + SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }} + URL: ${{ steps.wporg.outputs.url }} + VERSION: ${{ steps.tag.outputs.version }} + PKG: ${{ steps.pkg.outputs.dir }} + run: | + set -euo pipefail + svn_dir="$RUNNER_TEMP/svn" + svn checkout --depth immediates --non-interactive "$URL" "$svn_dir" + cd "$svn_dir" + svn update --set-depth infinity --non-interactive trunk assets + if svn ls "$URL/tags/$VERSION" --non-interactive >/dev/null 2>&1; then + echo "::error::tags/$VERSION already exists on WordPress.org"; exit 1 + fi + rsync -rc --delete --exclude='.svn' "$PKG/" trunk/ + if [ -d "$GITHUB_WORKSPACE/.wordpress-org" ]; then + rsync -rc --delete --exclude='.svn' "$GITHUB_WORKSPACE/.wordpress-org/" assets/ + fi + svn add --force --quiet trunk assets + svn status | awk '/^!/ {print $2}' | xargs -r svn delete --quiet + svn copy --quiet trunk "tags/$VERSION" + svn status + svn commit --non-interactive --no-auth-cache \ + --username "$SVN_USERNAME" --password "$SVN_PASSWORD" \ + --message "Release $VERSION" diff --git a/.github/workflows/linked-issue.yml b/.github/workflows/linked-issue.yml new file mode 100644 index 0000000..2d9a3e4 --- /dev/null +++ b/.github/workflows/linked-issue.yml @@ -0,0 +1,54 @@ +name: Linked issue + +# Every change starts with an issue: a pull request must close at least one +# issue in this repo ("Closes #12" in its description). The release changelog +# is built from those issues. The "Protect main" ruleset makes this check +# required; Dependabot PRs pass automatically and repo admins can bypass. +# +# Don't want this rule? Set the repo variable REQUIRE_LINKED_ISSUE to "false" +# (bin/setup-github.sh --linked-issue off does it). The check then always +# passes, and the changelog uses pull request titles instead of issue titles. + +on: + pull_request: + types: [opened, edited, reopened, synchronize, ready_for_review] + +permissions: + pull-requests: read + issues: read + +jobs: + linked-issue: + name: Linked issue + runs-on: ubuntu-latest + steps: + - name: Check that the PR closes an issue + env: + GH_TOKEN: ${{ github.token }} + PR: ${{ github.event.pull_request.number }} + AUTHOR: ${{ github.event.pull_request.user.login }} + REQUIRED: ${{ vars.REQUIRE_LINKED_ISSUE }} + run: | + set -euo pipefail + if [ "$REQUIRED" = "false" ]; then + echo "REQUIRE_LINKED_ISSUE is false: no issue needed." + exit 0 + fi + if [ "$AUTHOR" = "dependabot[bot]" ]; then + echo "Dependabot PR: no issue needed." + exit 0 + fi + issues=$(gh api graphql -F owner="${GITHUB_REPOSITORY%/*}" -F name="${GITHUB_REPOSITORY#*/}" -F pr="$PR" -f query=' + query($owner: String!, $name: String!, $pr: Int!) { + repository(owner: $owner, name: $name) { + pullRequest(number: $pr) { + closingIssuesReferences(first: 50) { nodes { number title } } + } + } + }' --jq '.data.repository.pullRequest.closingIssuesReferences.nodes[] | "#\(.number) \(.title)"') + if [ -z "$issues" ]; then + echo "::error::This pull request does not close any issue. Create an issue for the change and add 'Closes #' to the PR description (one line per issue)." + exit 1 + fi + echo "Closes:" + echo "$issues" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..8ad129c --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,128 @@ +name: Release + +# Every merge to main is checked; a release is made only when the plugin zip +# would change (the package, filtered by .distignore, is compared with the one +# at the last release). Docs-, CI- or config-only merges make no release and +# no deploy. +# +# Steps, in order: +# 1. Work out the next version (patch by default; the merged PR's +# `release:minor` / `release:major` label bumps more) and the changelog +# (one line per issue the released PRs closed). +# 2. Write Version (plugin header), Stable tag and the changelog entry +# (readme.txt), and commit that to main as "Release vX.Y.Z [skip ci]". +# Pushed with the RELEASE_DEPLOY_KEY deploy key, which the ruleset lets bypass. +# 3. Tag that commit, build the zip from it, publish the GitHub release. +# 4. Deploy, only while the repo variable DEPLOY_ENABLED is 'true'. +# +# Optional repo variable: PLUGIN_SLUG (zip folder name; defaults to the repo name). + +on: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: write + pull-requests: read + issues: read + +concurrency: + group: release + cancel-in-progress: false + +jobs: + release: + runs-on: ubuntu-latest + # The bot's own release commit never needs another release. The author is + # checked too, so a pull request titled "Release v..." still gets released. + if: ${{ !(startsWith(github.event.head_commit.message, 'Release v') && github.event.head_commit.author.name == 'github-actions[bot]') }} + outputs: + released: ${{ steps.publish.outputs.released }} + tag: ${{ steps.plan.outputs.tag }} + env: + GH_TOKEN: ${{ github.token }} + steps: + - name: Prepare + # Outside the checkout, so the changelog never ends up in the zip or the commit. + run: echo "CHANGELOG_FILE=$RUNNER_TEMP/changelog.txt" >> "$GITHUB_ENV" + + - name: Check out main with history and tags + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: main + fetch-depth: 0 + # Pushes the release commit with the "release-bot" deploy key, which the + # "Protect main" ruleset lets bypass (bin/setup-github.sh sets both up). + # Without the secret it falls back to the workflow token (unprotected repos). + ssh-key: ${{ secrets.RELEASE_DEPLOY_KEY }} + + - name: Plan release + id: plan + run: bash .github/scripts/release-plan.sh + + - name: Write version and changelog + if: steps.plan.outputs.release == 'true' + env: + VERSION: ${{ steps.plan.outputs.version }} + run: | + bash .github/scripts/stamp-version.sh "$VERSION" "$CHANGELOG_FILE" + git diff --stat + + - name: Commit release to main + if: steps.plan.outputs.release == 'true' + env: + TAG: ${{ steps.plan.outputs.tag }} + run: | + set -euo pipefail + git config user.name 'github-actions[bot]' + git config user.email '41898282+github-actions[bot]@users.noreply.github.com' + git commit --all --message "Release $TAG [skip ci]" --message "$(cat "$CHANGELOG_FILE")" + if ! git push origin HEAD:main; then + echo "::error::Could not push the release commit to main. Check that the RELEASE_DEPLOY_KEY secret and the 'release-bot' deploy key exist and that the 'Protect main' ruleset lets deploy keys bypass (bin/setup-github.sh sets this up), or that main has not moved during the run." + exit 1 + fi + echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT" + id: commit + + - name: Build release zip + if: steps.plan.outputs.release == 'true' + id: build + run: | + set -euo pipefail + . .github/scripts/lib.sh + slug="${{ vars.PLUGIN_SLUG }}" + slug="${slug:-${GITHUB_REPOSITORY#*/}}" + [[ "$slug" =~ ^[a-z0-9][a-z0-9-]*$ ]] || { echo "::error::bad plugin slug '$slug'"; exit 1; } + stage="$RUNNER_TEMP/stage" + build_package "$stage/$slug" + test -f "$stage/$slug/$(main_plugin_file)" + (cd "$stage" && zip -r -q "$GITHUB_WORKSPACE/$slug.zip" "$slug") + unzip -l "$slug.zip" + echo "zip=$slug.zip" >> "$GITHUB_OUTPUT" + + - name: Tag and publish GitHub release + if: steps.plan.outputs.release == 'true' + id: publish + env: + TAG: ${{ steps.plan.outputs.tag }} + SHA: ${{ steps.commit.outputs.sha }} + ZIP: ${{ steps.build.outputs.zip }} + run: | + set -euo pipefail + [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::bad tag $TAG"; exit 1; } + gh release create "$TAG" "$ZIP" \ + --target "$SHA" \ + --title "$TAG" \ + --notes-file "$CHANGELOG_FILE" + echo "released=true" >> "$GITHUB_OUTPUT" + + deploy: + needs: release + if: needs.release.outputs.released == 'true' && vars.DEPLOY_ENABLED == 'true' + uses: ./.github/workflows/deploy.yml + with: + tag: ${{ needs.release.outputs.tag }} + deploy: true + secrets: inherit diff --git a/.gitignore b/.gitignore index 5af8163..f4aeb9f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,18 +1,80 @@ -# OS / editors +# -------------------------------------------------- +# OS +# -------------------------------------------------- .DS_Store Thumbs.db -.idea/ -.vscode/ -*.swp -# Dependencies and build output +# -------------------------------------------------- +# Logs +# -------------------------------------------------- +*.log +npm-debug.log* + +# -------------------------------------------------- +# Environment (copy .env.example to .env) +# -------------------------------------------------- +.env +!.env.example + +# -------------------------------------------------- +# Node +# -------------------------------------------------- node_modules/ -vendor/ -dist/ -*.zip -*.tar.gz -# Logs and local tooling -*.log +# -------------------------------------------------- +# Composer +# -------------------------------------------------- +/vendor/ + +# -------------------------------------------------- +# Tooling caches +# -------------------------------------------------- +.phpcs.cache +.eslintcache +.stylelintcache +phpcs-report.xml +.phpunit.result.cache +.phpunit.cache/ .wp-env.override.json + +# -------------------------------------------------- +# Database / Local Development +# -------------------------------------------------- +*.sql +*.sqlite +database/ + +# -------------------------------------------------- +# Dreamweaver (legacy) +# -------------------------------------------------- +_notes +_compareTemp +configs/ +dwsync.xml +includes/_notes/dwsync.xml +/dwsync.xml +dw_php_codehinting.config +*.mno +*.lck + +# -------------------------------------------------- +# Release build output +# -------------------------------------------------- +/release/ +/*.zip + +# -------------------------------------------------- +# IDE / Editors (incl. SFTP sync configs) +# -------------------------------------------------- +.vscode/ +.vscodeignore +.idea/ +sftp.json + +# -------------------------------------------------- +# Project-specific (kept from this repo) +# -------------------------------------------------- +*.swp +dist/ +*.tar.gz .claude/ diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..2bd5a0a --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +22 diff --git a/.wordpress-org/blueprints/blueprint.json b/.wordpress-org/blueprints/blueprint.json new file mode 100644 index 0000000..a32f0aa --- /dev/null +++ b/.wordpress-org/blueprints/blueprint.json @@ -0,0 +1,40 @@ +{ + "$schema": "https://playground.wordpress.net/blueprint-schema.json", + "meta": { + "title": "StackFolio demo", + "description": "Installs the latest StackFolio release with sample albums and a demo page.", + "author": "wpgenius" + }, + "landingPage": "/stackfolio-demo/", + "preferredVersions": { + "php": "8.3", + "wp": "latest" + }, + "features": { + "networking": true + }, + "login": true, + "steps": [ + { + "step": "installPlugin", + "pluginData": { + "resource": "url", + "url": "https://github.com/wpgenius/stackfolio/releases/latest/download/stackfolio.zip" + }, + "options": { + "activate": true + } + }, + { + "step": "setSiteOptions", + "options": { + "blogname": "StackFolio demo", + "permalink_structure": "/%postname%/" + } + }, + { + "step": "runPHP", + "code": " 'image/jpeg', 'post_title' => $title, 'post_excerpt' => 'Sample photo: ' . $title, 'post_status' => 'inherit' ), $file );\n\twp_update_attachment_metadata( $id, wp_generate_attachment_metadata( $id, $file ) );\n\treturn $id;\n}\n$albums = array(\n\tarray( 'Beach Wedding', 'Weddings', array( 38, 120, 200 ), \"https://www.youtube.com/watch?v=aqz-KE-bpKQ\" ),\n\tarray( 'Garden Ceremony', 'Weddings', array( 70, 150, 90 ), '' ),\n\tarray( 'Music Festival', 'Events', array( 200, 60, 90 ), \"https://vimeo.com/76979871\" ),\n\tarray( 'Charity Run', 'Events', array( 230, 140, 40 ), '' ),\n\tarray( 'Studio Portraits', 'Portraits', array( 110, 80, 170 ), '' ),\n\tarray( 'City Lights', 'Portraits', array( 30, 40, 70 ), '' ),\n);\nforeach ( $albums as $album ) {\n\tlist( $title, $category, $rgb, $video ) = $album;\n\t$post_id = wp_insert_post( array( 'post_type' => 'stackfolio_album', 'post_status' => 'publish', 'post_title' => $title ) );\n\t$media = array();\n\tfor ( $i = 1; $i <= 4; $i++ ) {\n\t\t$media[] = stackfolio_demo_image( $title . ' ' . $i, array( ( $rgb[0] + $i * 25 ) % 255, ( $rgb[1] + $i * 15 ) % 255, $rgb[2] ) );\n\t}\n\tset_post_thumbnail( $post_id, $media[0] );\n\tupdate_post_meta( $post_id, '_stackfolio_media', implode( ',', $media ) );\n\tupdate_post_meta( $post_id, '_stackfolio_video_links', $video );\n\twp_set_object_terms( $post_id, $category, 'stackfolio_category' );\n}\nwp_insert_post( array( 'post_type' => 'page', 'post_status' => 'publish', 'post_name' => 'stackfolio-demo', 'post_title' => 'StackFolio demo',\n\t'post_content' => \"

Click a cover to open the album. Use the buttons to filter by category.

\\n\\n

Edit albums under StackFolio in the dashboard.

\" ) );" + } + ] +} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4ffd870 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing + +Thanks for helping improve StackFolio. + +## How a change gets in + +Every change starts with an issue, and the changelog of each release is built +from the issues it closes. + +1. **Open an issue** (or comment on an existing one) describing the bug or + the change. For anything large, wait for a reply before you start. +2. **Fork and branch** from `main`. Use a short descriptive branch name, such + as `fix-uninstall` or `settings-radio-field`. +3. **Make the change** and run the checks below. +4. **Open a pull request** whose description says what changed and includes + `Closes #` (one line per issue). The *Linked issue* check + fails without it. +5. A maintainer squash-merges it. If the plugin itself changed, a new version + is released automatically. + +## Local setup + +```bash +composer install +``` + +```bash +npm ci +``` + +A WordPress site to try it in: `cp .env.example .env && docker compose up -d`, +then open http://localhost:8000. + +## Checks to run before a pull request + +| Command | What it checks | +|---|---| +| `composer lint` | PHP syntax | +| `composer phpcs` | WordPress Coding Standards (`composer phpcbf` fixes most issues) | +| `composer phpstan` | Static analysis | +| `composer test` | Unit tests | +| `npm run lint` | JS and CSS | + +CI runs the same checks, plus WordPress Plugin Check, on every pull request. + +## Code style + +- Follow the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/); + PHPCS enforces them. +- One class per file in `includes/`, named `class-stackfolio-*.php` after the + class. See "Structure" in the README. +- The block in `blocks/album-grid/` is plain JavaScript with no build step; + edit `index.js` directly. +- Escape output, sanitise input, check nonces and capabilities. +- Keep PHP 7.4 compatible (the minimum in the plugin header). +- Don't edit the version or the changelog in `readme.txt`: the release + workflow writes them. + +## Reporting a security issue + +Please don't open a public issue. See [SECURITY.md](SECURITY.md). diff --git a/README.md b/README.md index af86f1e..e8baa97 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ **Stunning photo & video albums for WordPress.** +[![Try it in your browser](https://img.shields.io/badge/WordPress_Playground-Try_it_in_your_browser-3858e9?logo=wordpress)](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpgenius/stackfolio/main/.wordpress-org/blueprints/blueprint.json) + StackFolio shows a filterable grid of album covers. Click a cover and the whole album (photos, Media Library videos, YouTube, YouTube playlists and Vimeo) opens in a lightGallery popup. Use it as a Gutenberg block, an Elementor widget or the `[stackfolio]` shortcode. StackFolio is the successor of Album Station and migrates its albums automatically. @@ -22,6 +24,38 @@ StackFolio is the successor of Album Station and migrates its albums automatical | `includes/class-stackfolio-migration.php` | One-time Album Station migration | | `assets/vendor/` | lightGallery 2.9.0 and Isotope 3.0.6 (GPLv3), Vimeo Player API 2.30.4 (MIT) | +## Try it in your browser + +[**Open the demo in WordPress Playground**](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/wpgenius/stackfolio/main/.wordpress-org/blueprints/blueprint.json): it installs the latest release with six sample albums and a demo page. (Playground downloads `releases/latest/download/stackfolio.zip`, so it needs at least one release.) + +## How changes ship + +``` +issue → branch → pull request (Closes #N) → squash merge to main → automatic release → deploy (if enabled) +``` + +- **`main` is protected.** Changes go through pull requests, merged with squash. Repository admins can still bypass the rules. +- **Every PR closes an issue.** The *Linked issue* check fails a PR without `Closes #N`. One request with several changes = one issue per change, delivered in one PR. +- **CI** runs on every PR and must pass: PHP 7.4–8.5 syntax and unit tests, PHPCS, PHPStan, JS/CSS lint and WordPress Plugin Check. Plugin Check fails when `Tested up to` in `readme.txt` is behind the latest WordPress, so bump it after testing each new WordPress version. +- **Releases are automatic.** On each merge to `main`, the [Release workflow](.github/workflows/release.yml) releases only if the plugin zip would change (everything [`.distignore`](.distignore) doesn't exclude). It bumps the version (patch by default, or minor/major with the `release:minor` / `release:major` label), writes the changelog (one line per closed issue) and the version into `readme.txt` and the plugin header, commits that to `main`, tags it and publishes a GitHub release with `stackfolio.zip`. +- **Deploys are off.** The [Deploy workflow](.github/workflows/deploy.yml) targets WordPress.org SVN (`DEPLOY_METHOD=wporg`) and runs only while the repo variable `DEPLOY_ENABLED` is `true`. Turn it on once the plugin is approved on WordPress.org and the `SVN_USERNAME` / `SVN_PASSWORD` secrets are set. + +## Development + +```bash +composer install && npm ci +``` + +| Command | What it checks | +|---|---| +| `composer lint` | PHP syntax | +| `composer phpcs` | WordPress Coding Standards (`composer phpcbf` fixes most issues) | +| `composer phpstan` | Static analysis | +| `composer test` | Unit tests | +| `npm run lint` | JS and CSS (Node 22.12 or newer) | + +A local site: `cp .env.example .env && docker compose up -d`, then open http://localhost:8000. + ## Developer hooks - `stackfolio_post_type_args`, `stackfolio_taxonomy_args` – change registration arguments diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b94b046 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,16 @@ +# Security policy + +## Supported versions + +Only the latest release receives security fixes. + +## Reporting a vulnerability + +Please report security issues privately, not in a public issue: + +1. Go to the repository's **Security** tab. +2. Click **Report a vulnerability** and describe the issue, the affected + version and how to reproduce it. + +You'll get a reply within a few working days. Once a fix is released, the +advisory is published with credit to you, unless you'd rather stay anonymous. diff --git a/assets/css/stackfolio-admin.css b/assets/css/stackfolio-admin.css index 432a81b..7da4af5 100644 --- a/assets/css/stackfolio-admin.css +++ b/assets/css/stackfolio-admin.css @@ -2,9 +2,11 @@ margin: 1.5em 0 0.25em; font-size: 14px; } + .stackfolio-metabox__heading:first-child { margin-top: 0.5em; } + .stackfolio-media-list { display: flex; flex-wrap: wrap; @@ -15,9 +17,11 @@ background: #f6f7f7; border: 1px dashed #c3c4c7; } + .stackfolio-media-list:empty::before { content: ""; } + .stackfolio-media-item { position: relative; width: 100px; @@ -28,12 +32,14 @@ cursor: move; overflow: hidden; } + .stackfolio-media-item img { display: block; width: 100%; height: 100%; object-fit: cover; } + .stackfolio-media-item.is-video { display: flex; flex-direction: column; @@ -45,23 +51,27 @@ background: #1d2327; color: #fff; } + .stackfolio-media-item.is-video .dashicons { width: 32px; height: 32px; font-size: 32px; } + .stackfolio-media-item__name { margin-top: 4px; font-size: 11px; line-height: 1.3; - word-break: break-word; + overflow-wrap: anywhere; max-height: 2.6em; overflow: hidden; } + .stackfolio-media-item--placeholder { background: #dcdcde; border-style: dashed; } + .stackfolio-media-item__remove { position: absolute; top: 2px; @@ -78,20 +88,25 @@ cursor: pointer; opacity: 0; } + .stackfolio-media-item:hover .stackfolio-media-item__remove, .stackfolio-media-item__remove:focus { opacity: 1; } + .stackfolio-position { margin-top: 1em; } + .stackfolio-position legend { font-weight: 600; margin-bottom: 4px; } + .stackfolio-position label { margin-right: 1.5em; } + .stackfolio-warning { color: #b32d2e; margin: 4px 0; diff --git a/assets/css/stackfolio.css b/assets/css/stackfolio.css index 58b7d71..7854dc2 100644 --- a/assets/css/stackfolio.css +++ b/assets/css/stackfolio.css @@ -10,12 +10,14 @@ } @media (max-width: 1024px) { + .stackfolio { --sf-cols: var(--stackfolio-columns-tablet, 2); } } @media (max-width: 767px) { + .stackfolio { --sf-cols: var(--stackfolio-columns-mobile, 1); } @@ -53,7 +55,7 @@ line-height: 1.4; color: inherit; background: transparent; - border: 1px solid currentColor; + border: 1px solid currentcolor; border-radius: 999px; cursor: pointer; transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease; @@ -173,6 +175,7 @@ } @media (prefers-reduced-motion: reduce) { + .stackfolio-cover img, .stackfolio-filter { transition: none; @@ -211,6 +214,7 @@ } @media screen and (max-width: 782px) { + .admin-bar .stackfolio-lightbox .lg-outer, .admin-bar .stackfolio-lightbox .lg-backdrop { top: 46px; diff --git a/assets/js/stackfolio-admin.js b/assets/js/stackfolio-admin.js index d80e46c..e33b269 100644 --- a/assets/js/stackfolio-admin.js +++ b/assets/js/stackfolio-admin.js @@ -1,44 +1,63 @@ -/* global jQuery, wp, stackfolioAdmin */ +/* global jQuery, stackfolioAdmin */ ( function ( $ ) { 'use strict'; $( function () { - var $list = $( '#stackfolio-media-list' ); - var $input = $( '#stackfolio-media' ); - var $clear = $( '#stackfolio-clear-media' ); - var frame; + const $list = $( '#stackfolio-media-list' ); if ( ! $list.length ) { return; } + const $input = $( '#stackfolio-media' ); + const $clear = $( '#stackfolio-clear-media' ); + let frame; + function sync() { - var ids = $list.children( '.stackfolio-media-item' ).map( function () { - return $( this ).data( 'id' ); - } ).get(); + const ids = $list + .children( '.stackfolio-media-item' ) + .map( function () { + return $( this ).data( 'id' ); + } ) + .get(); $input.val( ids.join( ',' ) ); $clear.prop( 'hidden', ids.length === 0 ); } function itemHtml( attachment ) { - var $li = $( '
  • ' ).attr( 'data-id', attachment.id ); + const $li = $( '
  • ' ).attr( + 'data-id', + attachment.id + ); if ( attachment.type === 'video' ) { $li.addClass( 'is-video' ) - .append( '' ) - .append( $( '' ).text( attachment.title || stackfolioAdmin.video ) ); + .append( + '' + ) + .append( + $( + '' + ).text( attachment.title || stackfolioAdmin.video ) + ); } else { - var size = attachment.sizes && attachment.sizes.thumbnail ? attachment.sizes.thumbnail : attachment; + const size = + attachment.sizes && attachment.sizes.thumbnail + ? attachment.sizes.thumbnail + : attachment; $li.append( $( '' ).attr( 'src', size.url ) ); } $li.append( - $( '' ).attr( 'aria-label', stackfolioAdmin.remove ) + $( + '' + ).attr( 'aria-label', stackfolioAdmin.remove ) ); return $li; } $list.sortable( { items: '.stackfolio-media-item', - placeholder: 'stackfolio-media-item stackfolio-media-item--placeholder', + placeholder: + 'stackfolio-media-item stackfolio-media-item--placeholder', tolerance: 'pointer', update: sync, } ); @@ -69,18 +88,23 @@ } ); frame.on( 'select', function () { - var existing = $input.val() ? $input.val().split( ',' ) : []; - frame.state().get( 'selection' ).each( function ( model ) { - var attachment = model.toJSON(); - if ( existing.indexOf( String( attachment.id ) ) === -1 ) { - $list.append( itemHtml( attachment ) ); - existing.push( String( attachment.id ) ); - } - } ); + const existing = $input.val() ? $input.val().split( ',' ) : []; + frame + .state() + .get( 'selection' ) + .each( function ( model ) { + const attachment = model.toJSON(); + if ( + existing.indexOf( String( attachment.id ) ) === -1 + ) { + $list.append( itemHtml( attachment ) ); + existing.push( String( attachment.id ) ); + } + } ); sync(); } ); frame.open(); } ); } ); -}( jQuery ) ); +} )( jQuery ); diff --git a/assets/js/stackfolio.js b/assets/js/stackfolio.js index 1c7aee2..b0c5990 100644 --- a/assets/js/stackfolio.js +++ b/assets/js/stackfolio.js @@ -4,7 +4,7 @@ ( function () { 'use strict'; - var PLUGINS = { + const PLUGINS = { video: 'lgVideo', thumbnail: 'lgThumbnail', zoom: 'lgZoom', @@ -15,15 +15,15 @@ function getConfig( root ) { try { return JSON.parse( root.getAttribute( 'data-stackfolio' ) ) || {}; - } catch ( e ) { + } catch { return {}; } } function openAlbum( card ) { - var root = card.closest( '.stackfolio' ); - var config = root ? getConfig( root ) : {}; - var items; + const root = card.closest( '.stackfolio' ); + const config = root ? getConfig( root ) : {}; + let items; if ( typeof window.lightGallery !== 'function' ) { return; @@ -31,28 +31,28 @@ try { items = JSON.parse( card.getAttribute( 'data-items' ) ); - } catch ( e ) { + } catch { return; } if ( ! items || ! items.length ) { return; } - var plugins = ( config.plugins || [] ) + const plugins = ( config.plugins || [] ) .map( function ( name ) { return window[ PLUGINS[ name ] ]; } ) .filter( Boolean ); - var classes = [ 'stackfolio-lightbox' ]; + const classes = [ 'stackfolio-lightbox' ]; if ( config.hideThumbsFullscreen ) { classes.push( 'stackfolio-lightbox--hide-thumbs-fs' ); } - var gallery = window.lightGallery( card, { + const gallery = window.lightGallery( card, { dynamic: true, dynamicEl: items, - plugins: plugins, + plugins, // lightGallery is used under its GPLv3 licence; StackFolio is GPLv3 too. licenseKey: 'GPLv3', addClass: classes.join( ' ' ), @@ -80,26 +80,33 @@ function setActive( buttons, active ) { buttons.forEach( function ( button ) { - var isActive = button === active; + const isActive = button === active; button.classList.toggle( 'is-active', isActive ); button.setAttribute( 'aria-pressed', isActive ? 'true' : 'false' ); } ); } function initFilters( root ) { - var grid = root.querySelector( '.stackfolio-grid' ); - var buttons = Array.prototype.slice.call( root.querySelectorAll( '.stackfolio-filter' ) ); + const grid = root.querySelector( '.stackfolio-grid' ); + const buttons = Array.prototype.slice.call( + root.querySelectorAll( '.stackfolio-filter' ) + ); if ( ! grid || ! buttons.length ) { return; } - var active = root.querySelector( '.stackfolio-filter.is-active' ) || buttons[ 0 ]; - var iso = null; + const active = + root.querySelector( '.stackfolio-filter.is-active' ) || + buttons[ 0 ]; + let iso = null; function applyFallback( filter ) { - Array.prototype.forEach.call( grid.querySelectorAll( '.stackfolio-item' ), function ( item ) { - item.hidden = filter !== '*' && ! item.matches( filter ); - } ); + Array.prototype.forEach.call( + grid.querySelectorAll( '.stackfolio-item' ), + function ( item ) { + item.hidden = filter !== '*' && ! item.matches( filter ); + } + ); } if ( typeof window.Isotope === 'function' ) { @@ -109,23 +116,30 @@ percentPosition: true, filter: active.getAttribute( 'data-filter' ), } ); - Array.prototype.forEach.call( grid.querySelectorAll( 'img' ), function ( img ) { - if ( ! img.complete ) { - img.addEventListener( 'load', function () { - iso.layout(); - }, { once: true } ); + Array.prototype.forEach.call( + grid.querySelectorAll( 'img' ), + function ( img ) { + if ( ! img.complete ) { + img.addEventListener( + 'load', + function () { + iso.layout(); + }, + { once: true } + ); + } } - } ); + ); } else { applyFallback( active.getAttribute( 'data-filter' ) ); } buttons.forEach( function ( button ) { button.addEventListener( 'click', function () { - var filter = button.getAttribute( 'data-filter' ); + const filter = button.getAttribute( 'data-filter' ); setActive( buttons, button ); if ( iso ) { - iso.arrange( { filter: filter } ); + iso.arrange( { filter } ); } else { applyFallback( filter ); } @@ -134,8 +148,11 @@ } function init( context ) { - var scope = context || document; - var roots = scope.matches && scope.matches( '.stackfolio' ) ? [ scope ] : scope.querySelectorAll( '.stackfolio' ); + const scope = context || document; + const roots = + scope.matches && scope.matches( '.stackfolio' ) + ? [ scope ] + : scope.querySelectorAll( '.stackfolio' ); Array.prototype.forEach.call( roots, function ( root ) { if ( root.getAttribute( 'data-stackfolio-ready' ) ) { @@ -150,7 +167,9 @@ // One delegated listener opens any album, including grids added later. document.addEventListener( 'click', function ( event ) { - var card = event.target.closest && event.target.closest( '.stackfolio .stackfolio-card[data-items]' ); + const card = + event.target.closest && + event.target.closest( '.stackfolio .stackfolio-card[data-items]' ); if ( card ) { event.preventDefault(); openAlbum( card ); @@ -166,22 +185,31 @@ } // Elementor: re-initialise widgets rendered in the editor preview. - var elementorHooked = false; + let elementorHooked = false; function hookElementor() { - if ( elementorHooked || ! window.elementorFrontend || ! window.elementorFrontend.hooks ) { + if ( + elementorHooked || + ! window.elementorFrontend || + ! window.elementorFrontend.hooks + ) { return; } elementorHooked = true; - [ 'stackfolio-album-grid.default', 'as-gallery.default' ].forEach( function ( name ) { - window.elementorFrontend.hooks.addAction( 'frontend/element_ready/' + name, function ( $scope ) { - init( $scope[ 0 ] || $scope ); - } ); - } ); + [ 'stackfolio-album-grid.default', 'as-gallery.default' ].forEach( + function ( name ) { + window.elementorFrontend.hooks.addAction( + 'frontend/element_ready/' + name, + function ( $scope ) { + init( $scope[ 0 ] || $scope ); + } + ); + } + ); } hookElementor(); if ( window.jQuery ) { window.jQuery( window ).on( 'elementor/frontend/init', hookElementor ); } - window.StackFolio = { init: init, open: openAlbum }; -}() ); + window.StackFolio = { init, open: openAlbum }; +} )(); diff --git a/assets/vendor/isotope/isotope.pkgd.min.js b/assets/vendor/isotope/isotope.pkgd.min.js new file mode 100644 index 0000000..7ca671c --- /dev/null +++ b/assets/vendor/isotope/isotope.pkgd.min.js @@ -0,0 +1,12 @@ +/*! + * Isotope PACKAGED v3.0.6 + * + * Licensed GPLv3 for open source use + * or Isotope Commercial License for commercial use + * + * https://isotope.metafizzy.co + * Copyright 2010-2018 Metafizzy + */ + +!function(t,e){"function"==typeof define&&define.amd?define("jquery-bridget/jquery-bridget",["jquery"],function(i){return e(t,i)}):"object"==typeof module&&module.exports?module.exports=e(t,require("jquery")):t.jQueryBridget=e(t,t.jQuery)}(window,function(t,e){"use strict";function i(i,s,a){function u(t,e,o){var n,s="$()."+i+'("'+e+'")';return t.each(function(t,u){var h=a.data(u,i);if(!h)return void r(i+" not initialized. Cannot call methods, i.e. "+s);var d=h[e];if(!d||"_"==e.charAt(0))return void r(s+" is not a valid method");var l=d.apply(h,o);n=void 0===n?l:n}),void 0!==n?n:t}function h(t,e){t.each(function(t,o){var n=a.data(o,i);n?(n.option(e),n._init()):(n=new s(o,e),a.data(o,i,n))})}a=a||e||t.jQuery,a&&(s.prototype.option||(s.prototype.option=function(t){a.isPlainObject(t)&&(this.options=a.extend(!0,this.options,t))}),a.fn[i]=function(t){if("string"==typeof t){var e=n.call(arguments,1);return u(this,t,e)}return h(this,t),this},o(a))}function o(t){!t||t&&t.bridget||(t.bridget=i)}var n=Array.prototype.slice,s=t.console,r="undefined"==typeof s?function(){}:function(t){s.error(t)};return o(e||t.jQuery),i}),function(t,e){"function"==typeof define&&define.amd?define("ev-emitter/ev-emitter",e):"object"==typeof module&&module.exports?module.exports=e():t.EvEmitter=e()}("undefined"!=typeof window?window:this,function(){function t(){}var e=t.prototype;return e.on=function(t,e){if(t&&e){var i=this._events=this._events||{},o=i[t]=i[t]||[];return o.indexOf(e)==-1&&o.push(e),this}},e.once=function(t,e){if(t&&e){this.on(t,e);var i=this._onceEvents=this._onceEvents||{},o=i[t]=i[t]||{};return o[e]=!0,this}},e.off=function(t,e){var i=this._events&&this._events[t];if(i&&i.length){var o=i.indexOf(e);return o!=-1&&i.splice(o,1),this}},e.emitEvent=function(t,e){var i=this._events&&this._events[t];if(i&&i.length){i=i.slice(0),e=e||[];for(var o=this._onceEvents&&this._onceEvents[t],n=0;n