Skip to content

CLAUDE.md

Latest commit

 

History

History
78 lines (54 loc) · 4 KB

CLAUDE.md

File metadata and controls

78 lines (54 loc) · 4 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Akeeba Release Maker is a CLI tool that automates software releases via Akeeba Release System (ARS) on Joomla sites. It uploads packages to remote storage (S3, Bunny CDN, FTP/SFTP), creates/updates ARS releases and items, publishes them, and pushes Joomla update streams to static hosting.

Commands

# Install dependencies
composer install

# Run the release process
php releasemaker.php release path/to/config.json5
php releasemaker.php release path/to/config.yaml --debug

# Run Rector for code quality analysis
vendor/bin/rector process --dry-run

There are no unit tests in this project.

Architecture

Entry Point & Execution Flow

releasemaker.php bootstraps a Silly (Symfony Console wrapper) CLI app. The single command release is handled by Command\Release, which:

  1. Loads configuration from a JSON5/YAML file via Configuration::fromFile()
  2. Validates that all configured step classes exist and implement StepInterface
  3. Executes each step sequentially by instantiating and calling execute()

Configuration System

Configuration is a singleton (Configuration::getInstance()) that holds all application state, divided into sections:

  • release — version, category, release notes
  • api — ARS API connection (endpoint, auth)
  • steps — ordered list of step classes to execute
  • connection — upload connection configs (S3, FTP, SFTP, Bunny)
  • updates — update stream publishing config
  • sources — file sources to upload
  • volatile — mutable runtime state shared between steps

Parser discovery: Configuration\Parser auto-discovers parsers in Configuration/Parser/ using @priority and @extension docblock annotations via reflection. Higher priority parsers are tried first. Three formats supported: JSON5, YAML, Legacy JSON.

Step Pipeline

Steps in src/Step/ extend AbstractStep and implement StepInterface (constructor takes SymfonyStyle, single execute() method):

  • Prepare — scans and catalogs files to upload
  • Deploy — uploads files to remote storage via Uploader implementations
  • Release — creates/updates the ARS release record
  • Items — creates/updates ARS items (one per uploaded file)
  • Publish — sets release and items to published state
  • Updates — pushes Joomla update XML streams to static hosting

Uploaders

Six implementations of Contracts\Uploader in src/Uploader/: S3, Bunny, NativeFtp, CurlFtp, NativeSftp, CurlSftp. Each takes a ConnectionConfiguration and provides upload(sourcePath, destPath). cURL variants serve as fallbacks when native PHP extensions (ext-ftp, ext-ssh2) are unavailable.

ARS Deployment

Deployment\ARSInterface defines the ARS API contract. ArsJoomla is the sole implementation, using the Joomla 4+ Web Services API (ARS 7.x and later). The ARSConnectorAware mixin instantiates it with the configured endpoint and token.

Key Patterns

  • Magic property access: MagicGetterAware / MagicSetterAware traits map $obj->prop to getProp() / setProp() methods on private properties. Configuration sections expose read-only properties via @property-read annotations.
  • Annotation-driven discovery: Configuration parsers are discovered by scanning @priority annotations in docblocks (not PHP attributes).
  • AKEEBAENGINE constant: Must be defined before using the akeeba/s3 library. Defined in releasemaker.php and rector.php.

Coding Conventions

  • Namespace root: Akeeba\ReleaseMaker\ with PSR-4 autoloading from src/
  • PHP 8.0+ required; platform target PHP 8.2 in Composer
  • Allman-style braces (opening brace on its own line for control structures and class/method declarations)
  • Tab indentation
  • Custom exception hierarchy in src/Exception/ with numeric exit codes defined in Contracts\ExceptionCode
  • File header: @package AkeebaReleaseMaker, @copyright, @license docblock on every PHP file