Skip to content

Releases

1.0.0-beta.6 - Align installation and Boost guidance with beta.5 baseline

Choose a tag to compare

@allanmcarvalho allanmcarvalho released this 18 Nov 22:14

Changed

  • Updated project documentation for the beta.5 release baseline (in the documentation for the 1.0.0-beta.6 cycle, including the “Unreleased” section of CHANGELOG.md and related install guidance).
  • Reordered the documented installation/migration steps so the “clean database” requirement is stated before running the migration command, helping prevent users from applying an incorrect migration sequence.
  • Added/clarified guidance for “published variant regeneration,” including when and how this regeneration step should be applied.

User impact

  • No direct runtime/code/config/API behavior changes are indicated.
  • This release is limited to documentation guidance and the order/clarity of operational steps.

Compatibility / Migration

  • Existing users do not need code changes.
  • Update your operational runbook/process to follow the clarified step ordering (clean database before migration) and apply the documented published variant regeneration requirement when applicable.

1.0.0-beta.5 - Consolidate Filoquent migrations into a single clean-install baseline

Choose a tag to compare

@allanmcarvalho allanmcarvalho released this 17 Nov 19:41

Changed

  • Updated the migration strategy to use a single consolidated baseline migration for clean installations.
  • The consolidated migration now directly creates the full schema for new installs, including:
    • The filoquent_uploads ledger
    • The filoquent_upload_namespace journal namespace, seeded with id=1 and a generated UUID
    • The filoquent_owner_tables coordination schema
  • Rollback recovery behavior was aligned with the new baseline structure, including added/updated safety guards based on the consolidated schema’s coordination/pending conditions.
  • The published/used migration set is now expected to be exactly one timestamped migration file: 2026_11_12_000000_create_filoquent_tables.php.

Removed

  • Deleted the earlier, separate timestamped migrations that previously created or modified these schema components (e.g., upload table creation, journal namespace changes, and owner coordination table creation/normalization).
  • As a result, environments that previously relied on those individual migrations to create or evolve tables will no longer receive those incremental changes from the package’s current migration set.

Compatibility / Migration Considerations

  • Historical migration-chain upgrades are no longer supported by this development baseline.
    • If you are upgrading an existing environment that depended on the older stepwise migrations, you should not expect this consolidated migration to “chain up” from historical states.
    • Plan to use an appropriate supported upgrade path or consider starting from a fresh database on the new baseline, as described in the updated documentation/release notes.
  • Rollback is explicitly refused when coordination/pending states indicate it would be unsafe to revert (for example, if pending coordination exists, if relevant journal/upload state indicates writers are still active, or if required cleanup/disablement has not occurred).

User Impact

  • New installations should have a simpler migration publish/install flow (single migration file) and a consistent ledger/journal/coordination schema created by one baseline migration.
  • Upgraders may encounter breaking behavior if they previously relied on the older multi-step migration chain or on rollback sequences tied to those removed migrations.

1.0.0-beta.4 - Add persisted regenerate-missing fallback for typed Assets

Choose a tag to compare

@allanmcarvalho allanmcarvalho released this 16 Nov 18:05

Added

  • Typed/generic Assets support with improved developer ergonomics for working with variant keys.
  • Read-only “magic” variant properties and passive isset() support for variant keys.
  • Persisted missing-asset regeneration capabilities:
    • Assets::regenerateMissing(keys, source?) (requires an appropriate model AssetContext, otherwise throws FiloquentException).
    • Optional model-aware regeneration context:
      • Assets can now accept an AssetContext.
      • get() can regenerate a missing key on demand when context is present; otherwise it returns null.
  • Middleware-driven regeneration configuration:
    • New #[RegenerateMissing] attribute for middleware classes to mark them for regeneration and optionally configure a regeneration “source”.
    • New src/Support/AssetContext to discover the configured regeneration middleware (via the attribute) and to invoke regeneration on models implementing the required regeneration support.
  • Integration of regeneration through casts:
    • AsFile casts propagate AssetContext so regeneration can occur based on the Eloquent model and cast key.
  • New upload/persistence capabilities to support extension workflows:
    • PendingUpload extended with optional existing manifest tracking, a list of keys, and a source.
    • FileWriter improvements:
      • Centralized middleware validation.
      • Normalization of PendingAsset lists.
      • Added storeMissing() to regenerate only missing keys based on an existing manifest.
    • Persistence updates for “extension” uploads:
      • When PendingUpload includes an existing manifest, the process locks for extension, stores only missing files, merges new variants into the parent manifest, updates filing state (including orphan handling), and tracks per-key extensions to influence finish-time behavior.
  • UploadIntent extension support:
    • Optional parentId with UUIDv7 validation.
    • Payload versioning (decode supports versions 1 and 2; encode emits version 1 or 2 accordingly).

Changed

  • Stricter regeneration and lifecycle safety checks in HasFiloquent helpers:
    • Regeneration requires models to be idle/not-dirty.
    • Keys are validated before regeneration.
    • Stale data mismatches and unsafe states are rejected (e.g., dirty/stale/borrowed/detached).
    • Regeneration requires a non-null middleware when regeneration is needed.
    • If saving fails, raw attributes are restored.
  • Stricter key validation in PendingAsset:
    • Uses an anchored ASCII regex and centralized validateKey/validateKeys helpers for consistent handling.
  • PendingAsset/PendingUpload and writer persistence flow updated to support more precise missing-key regeneration and merging.

Fixed

  • Test stability: disconnect native test DB sessions after lifecycle
    • Ensures native database sessions used during the test lifecycle are properly disconnected after lifecycle completion.
    • Prevents test pollution/leaks and avoids resource exhaustion or cross-test interference in environments that reuse long-lived processes or native connection pools.

Documentation

  • Added/updated typed Assets documentation and guidance related to the new typed/generic Assets usage patterns and regeneration behavior.

Internal Maintenance

  • PHPStan installation compatibility fix
    • Restricted phpstan/phpstan constraint to ^2.3.5 <2.3.6 for type coverage compatibility.
    • This helps ensure consistent static analysis results in CI/developer workflows.

Compatibility / Migration Notes

  • Regeneration requires an Assets instance created with a suitable AssetContext (derived from middleware + model/attribute). Calling regenerateMissing without the proper context will throw FiloquentException.
  • Middleware configuration is now mediated by the #[RegenerateMissing] attribute (and optional source selection). Ensure middleware classes are annotated appropriately and cast configurations embed/derive middleware info as expected.
  • Downgrading to older builds may limit management of committed “extended” upload workflows (older versions may not understand the new persisted extended manifests).
  • When using regeneration, models must satisfy the new lifecycle/state constraints (idle/not-dirty); unsafe states are rejected to prevent inconsistent manifests and writes.

Testing

  • No test additions or changes were explicitly reported in the provided commit summary.

1.0.0-beta.3 - Add filoquent:status diagnostics command

Choose a tag to compare

@allanmcarvalho allanmcarvalho released this 13 Nov 17:16

Added

  • New Artisan command: php artisan filoquent:status

    • Provides a read-only operational report of the current Filoquent environment and upload pipeline health.
    • Checks include:
      • Filesystem accessibility
        • Validates access to the configured filesystem and filoquent.base_path.
      • Database upload ledger health
        • Reads from the filoquent_uploads table and reports per-state upload counts.
        • Supports --connection to select the writer connection used for reading ledger data.
      • Redis upload journal availability
        • Verifies Redis connectivity via a probe.
        • Reports journal intent counts (using zcard) scoped via the SQL journal scope for the selected DB connection.
    • Read-only behavior: the command does not modify files, the filoquent_uploads ledger, or Redis journal contents.
  • Command registration and supporting internals

    • Registered in FiloquentServiceProvider.
    • Updated CommandRun::context() behavior to support status reporting correctly:
      • Ensures mode metadata is correctly set for filoquent:status.
      • Ensures limit is applied only when --limit is explicitly provided, preventing unintended context side effects for status-related flows.
  • Enhanced Redis journal support (for the command)

    • RedisUploadJournal adds:
      • ping() for Redis connectivity verification.
      • count(scope) for journal intent cardinality via zcard.
    • Includes strict validation for the new behaviors.
  • Testing

    • Added a StatusCommandTest suite covering:
      • Correct use of the private Redis journal connection.
      • Correct counting behavior scoped to the selected ledger scope.
      • Guarantees that the command does not mutate local storage, does not add ledger rows, does not leak Redis marker state, and keeps transactional behavior stable.
      • Graceful handling when storage backends, ledger rows, or required status inputs are unavailable.
      • No credential disclosure in Redis reporting.
      • Correct handling of --connection (including rejecting invalid connection names).
      • --silent behavior.
      • Remote storage accessibility via read probes.

Changed

  • Documentation and beta context updates
    • Updated beta/source identity wording to reference 1.0.0-beta.2 (clarifying historical development before that point).
    • Updated documentation targets to 1.0.0-beta.2 instead of 1.0.0-beta.1.
    • Updated AGENTS.md and CHANGELOG.md restructuring to present this capability under Added and improve beta identity/clarity.
    • Updated README.md and related skill docs to align beta targeting.
    • Updated resources/boost/skills/filoquent-development/SKILL.md with:
      • Discovery instructions (php artisan list filoquent)
      • filoquent:status usage and what it reports
      • --connection=uploads guidance
      • How to interpret counts
      • Operational expectations (including that credentials/adapter exception text are omitted)

Behavior notes (user-visible)

  • Exit status reliability

    • Returns SUCCESS only when all relevant checks succeed (filesystem, ledger, and Redis journal).
    • Otherwise returns FAILURE.
  • Availability/error signaling

    • When checks are unavailable, the command emits issue-key style identifiers such as:
      • status_filesystem_unavailable
      • status_ledger_unavailable
      • status_journal_unavailable
      • status_journal_count_unavailable
    • Includes suggested remediation actions.

Compatibility

  • This release primarily introduces a new read-only diagnostic capability (filoquent:status).
  • Internal context handling for filoquent:status was adjusted to prevent unintended mode/limit side effects, but no other API-level changes are stated beyond the new command.

Migration / upgrade guidance

  • Documentation for this beta release updates upgrade/target guidance to reference 1.0.0-beta.2.
  • As with beta artifacts, wording and behavior may continue to change prior to the stable 1.0.0 release.

1.0.0-beta.2 - Add middleware generator and native file attributes with persisted state enums

Choose a tag to compare

@allanmcarvalho allanmcarvalho released this 13 Nov 16:39

Added

  • New Artisan generator command: php artisan filoquent:make-middleware {name} {--force}

    • Implemented in src/Console/Commands/MakeMiddlewareCommand.php.
    • Generates a Filoquent upload middleware class using the new stub template resources/stubs/middleware.stub.
    • Generated namespace default: <rootNamespace>\Files.
    • The generated middleware includes a handle(Upload $file) method that delegates to $file->asset() and returns:
      • a PendingAsset, or
      • a non-empty list of results depending on what the upload resolves to.
    • Overwrite behavior: pass --force to control overwriting existing generated files.
  • Native File attributes and persisted state enums:

    • Introduces native support for File attributes and adds persisted state enums (as provided by commit 3604688).

Changed

  • Standardized middleware creation for the upload pipeline to align developer workflow with typical Laravel generator conventions.

Notes / Migration

  • To use the new middleware generator, run the new Artisan command to create the middleware class. Use --force if you intend to overwrite an existing middleware file.

1.0.0-beta.1 - Update beta release documentation and prerelease installation instructions

Choose a tag to compare

@allanmcarvalho allanmcarvalho released this 13 Nov 14:28

Changed

  • CHANGELOG.md

    • Added/updated a Changed entry describing the beta documentation updates.
    • Documented the updated Packagist installation approach (without requiring a local checkout).
    • Noted that maintainers may need to preserve version identifiers for later setup.
  • README.md

    • Updated maintainer/badge status from “Preview” → “Beta”.
    • Refined the README head description from “Preview file attributes…” → “File attributes…”.
    • Revised setup/requirements guidance to clarify that the prerelease is available on Packagist under the beta channel.
    • Added a warning that APIs may change before the stable release.
    • Updated Composer installation instructions to switch from a local path repository + dev requirement workflow to requiring a specific prerelease version via Packagist:
      • composer require artisan-toolbox/filoquent:1.0.0-alpha.1
  • Skill documentation (resources/boost/skills/filoquent-development/SKILL.md)

    • Replaced instructions that targeted an unpublished dev preview (including references to identity/version and specific PHP/Laravel constraints) with guidance for the published prerelease.
    • Kept the API-change warning for the beta/prerelease period.
    • Removed the custom Composer path repository setup guidance.
    • Updated Composer installation guidance to the direct, version-pinned Packagist approach:
      • composer require artisan-toolbox/filoquent:1.0.0-alpha.1

Testing

  • Updated tests/Unit/ReadmeHeadTest.php expectations so automated checks match the revised README head metadata (e.g., Preview → Beta badge text/image alt metadata and the updated head description).

1.0.0-alpha.1 - Stabilize CI/static analysis and expand validation coverage

Choose a tag to compare

@allanmcarvalho allanmcarvalho released this 13 Nov 11:54

Changed

  • Updated CI workflow coverage (SQLite + native DBs): Expanded the test workflow to run additional database scenarios, specifically SQLite and native DBs, to catch DB-specific regressions earlier.

  • Aligned PHPStan parallelism on Windows: Adjusted PHPStan configuration to limit parallelism on Windows by using a shared platform profile. This reduces the likelihood of platform-specific resource contention or configuration issues that can cause PHPStan failures or instability in Windows-based CI.

  • Maintainer checks can validate new source version: Updated the maintainer-checks behavior so that they can validate new source versions.

  • Development workflow pinned to the 1.x line: Updated the Filoquent development workflows to use the 1.x series to better align dev dependency expectations with the intended major version.

Added

  • AI and documentation skills standards: Added and/or updated repository standards for AI and documentation skills, including guidance around skill definition and authoring/review workflows, to keep documentation/skill instructions consistent with actual behavior.

Fixed

  • PHPStan reliability on Windows: Limited PHPStan parallelism on Windows to improve static-analysis stability in Windows CI runs.

  • Maintainer validation for new source versions: Ensured maintainer checks can validate new source revisions.

Internal Maintenance

  • Repository bootstrap: Initial commit establishes the base project structure.

Compatibility / Migration Notes

  • End users: No direct runtime/API changes are described in these changes.
  • Contributors / maintainers:
    • CI runs may take longer due to the expanded database test matrix (SQLite + native DBs).
    • If you run PHPStan locally or in Windows CI, expect improved stability from the Windows parallelism change.
    • For development workflows using Filoquent, ensure your local setup aligns with the updated 1.x workflow expectations.
    • When updating documentation or agent/skill content, follow the newly added AI/documentation skills standards files.