PHPackages                             lofye/foundry-framework - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. lofye/foundry-framework

ActiveLibrary

lofye/foundry-framework
=======================

Foundry: an explicit, LLM-first PHP web framework

v0.5.0(yesterday)11↓100%MITPHPPHP ^8.4

Since Mar 6Pushed yesterday1 watchersCompare

[ Source](https://github.com/lofye/foundry-framework)[ Packagist](https://packagist.org/packages/lofye/foundry-framework)[ RSS](/packages/lofye-foundry-framework/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (4)Versions (10)Used By (0)

Foundry Framework
=================

[](#foundry-framework)

Foundry is a production-minded, explicit, deterministic, LLM-first PHP framework for building feature-local web apps. Visit [FoundryFramework.org](https://foundryframework.org) for extensive documentation.

It is optimized for:

- explicit contracts
- deterministic generation
- machine-readable inspection
- small safe edit surfaces
- strong verification and testing

Foundry now includes a semantic compiler core:

- source files are compiled into a canonical application graph
- runtime indexes are projections of that graph
- verification and impact analysis operate over compiled graph state

Initial Prompt: Derek Martin Architect: ChatGPT-5.3 Engineer: GPT-5.3-Codex (Extra High) License: MIT.

Runtime and Language
--------------------

[](#runtime-and-language)

- PHP `^8.4`
- Composer-based

Install and Run (Packagist)
---------------------------

[](#install-and-run-packagist)

```
# Create a new project folder
mkdir my-foundry-app
cd my-foundry-app

# Install Foundry
composer require lofye/foundry-framework

# Initialize a new Foundry app in this folder
php vendor/bin/foundry init app . --name=acme/my-foundry-app

# Install project dependencies
composer install

# Generate indexes and verify contracts
php vendor/bin/foundry compile graph --json
php vendor/bin/foundry verify graph --json
php vendor/bin/foundry verify contracts --json
php -S 127.0.0.1:8000 app/platform/public/index.php
```

Upgrade Foundry in an App
-------------------------

[](#upgrade-foundry-in-an-app)

```
composer update lofye/foundry
php vendor/bin/foundry compile graph --json
php vendor/bin/foundry verify graph --json
php vendor/bin/foundry verify contracts --json
```

Local MinIO (Fix + Verify)
--------------------------

[](#local-minio-fix--verify)

Your MinIO install issue is typically a port conflict on `127.0.0.1:9000`.

Check what owns the ports:

```
lsof -nP -iTCP:9000 -sTCP:LISTEN
lsof -nP -iTCP:9001 -sTCP:LISTEN
```

Option A: keep defaults and stop the conflicting process.

Option B: run MinIO on alternate ports (recommended if 9000 is already used):

```
mkdir -p "$HOME/minio-data"
export MINIO_ROOT_USER="foundry"
export MINIO_ROOT_PASSWORD="foundry-dev-secret"
minio server "$HOME/minio-data" --address ":9100" --console-address ":9101"
```

Configure `mc` and create a bucket:

```
mc alias set foundry http://127.0.0.1:9100 foundry foundry-dev-secret
mc mb --ignore-existing foundry/foundry-dev
mc ls foundry
```

Health check:

```
curl -sS http://127.0.0.1:9100/minio/health/live
```

Notes:

- `/home/shared` is a Linux path; on macOS use an existing directory like `$HOME/minio-data`.
- avoid default credentials (`minioadmin:minioadmin`) for persistent local setups.

Core Workflow for LLMs
----------------------

[](#core-workflow-for-llms)

Use this loop for every change:

1. Inspect current reality.
2. Edit the minimum feature-local files.
3. Compile graph.
4. Inspect diagnostics and impact.
5. Verify graph/contracts/rules.
6. Run tests.

Recommended command sequence:

```
php vendor/bin/foundry inspect feature  --json
php vendor/bin/foundry inspect context  --json
php vendor/bin/foundry compile graph --json
php vendor/bin/foundry inspect graph --json
php vendor/bin/foundry inspect impact --file=app/features//feature.yaml --json
php vendor/bin/foundry verify graph --json
php vendor/bin/foundry generate context  --json
php vendor/bin/foundry verify feature  --json
php vendor/bin/foundry verify contracts --json
php vendor/bin/foundry verify auth --json
php vendor/bin/foundry verify cache --json
php vendor/bin/foundry verify events --json
php vendor/bin/foundry verify jobs --json
vendor/bin/phpunit
```

App Structure
-------------

[](#app-structure)

```
app/
  features/
    /
      feature.yaml
      action.php
      input.schema.json
      output.schema.json
      context.manifest.json
      queries.sql
      permissions.yaml
      cache.yaml
      events.yaml
      jobs.yaml
      prompts.md
      tests/
  generated/
    routes.php
    feature_index.php
    schema_index.php
    permission_index.php
    event_index.php
    job_index.php
    cache_index.php
    scheduler_index.php
    webhook_index.php
  .foundry/
    build/
      graph/
      projections/
      manifests/
      diagnostics/
  platform/
    bootstrap/
    config/
    migrations/
    public/index.php

```

Rules:

- `app/features/*` is source-of-truth behavior.
- `app/.foundry/build/*` is canonical compiled output.
- `app/generated/*` remains a compatibility mirror of runtime projections.
- hot-path runtime reads generated projections (no folder scanning in request path).

Feature Contract
----------------

[](#feature-contract)

Each feature must define:

- manifest (`feature.yaml`)
- action implementation (`action.php` implementing `Foundry\Feature\FeatureAction`)
- input/output schemas
- context manifest
- tests declared in `feature.yaml`

Optional feature-local files:

- `queries.sql`, `permissions.yaml`, `cache.yaml`, `events.yaml`, `jobs.yaml`, `prompts.md`

CLI Surface
-----------

[](#cli-surface)

All inspection, verification, and planning commands support `--json`.

Compile:

```
php vendor/bin/foundry compile graph --json
php vendor/bin/foundry compile graph --feature= --json
php vendor/bin/foundry compile graph --changed-only --json
```

Architecture analysis:

```
php vendor/bin/foundry doctor --json
php vendor/bin/foundry doctor --strict --json
php vendor/bin/foundry doctor --feature= --json
```

Graph visualization:

```
php vendor/bin/foundry graph visualize --json
php vendor/bin/foundry graph visualize --events --format=mermaid --json
php vendor/bin/foundry graph visualize --routes --format=dot --json
php vendor/bin/foundry graph visualize --caches --feature= --format=svg --json
php vendor/bin/foundry graph visualize --pipeline --format=mermaid --json
```

AI prompt loop:

```
php vendor/bin/foundry prompt "add bookmark endpoint for posts" --json
php vendor/bin/foundry prompt "add bookmark endpoint for posts" --feature-context --dry-run --json
php vendor/bin/foundry preview notification  --json
```

Inspect:

```
php vendor/bin/foundry inspect graph --json
php vendor/bin/foundry inspect build --json
php vendor/bin/foundry inspect node  --json
php vendor/bin/foundry inspect dependencies  --json
php vendor/bin/foundry inspect dependents  --json
php vendor/bin/foundry inspect pipeline --json
php vendor/bin/foundry inspect execution-plan  --json
php vendor/bin/foundry inspect guards --json
php vendor/bin/foundry inspect guards  --json
php vendor/bin/foundry inspect interceptors --json
php vendor/bin/foundry inspect interceptors --stage= --json
php vendor/bin/foundry inspect impact  --json
php vendor/bin/foundry inspect impact --file= --json
php vendor/bin/foundry inspect affected-tests  --json
php vendor/bin/foundry inspect affected-features  --json
php vendor/bin/foundry inspect extensions --json
php vendor/bin/foundry inspect extension  --json
php vendor/bin/foundry inspect packs --json
php vendor/bin/foundry inspect pack  --json
php vendor/bin/foundry inspect compatibility --json
php vendor/bin/foundry inspect migrations --json
php vendor/bin/foundry inspect definition-format  --json
php vendor/bin/foundry inspect resource  --json
php vendor/bin/foundry inspect notification  --json
php vendor/bin/foundry inspect api  --json
php vendor/bin/foundry inspect feature  --json
php vendor/bin/foundry inspect route   --json
php vendor/bin/foundry inspect auth  --json
php vendor/bin/foundry inspect cache  --json
php vendor/bin/foundry inspect events  --json
php vendor/bin/foundry inspect jobs  --json
php vendor/bin/foundry inspect context  --json
php vendor/bin/foundry inspect dependencies  --json
```

Generate:

```
php vendor/bin/foundry generate feature  --json
php vendor/bin/foundry generate starter server-rendered --json
php vendor/bin/foundry generate starter api --json
php vendor/bin/foundry generate resource  --definition= --json
php vendor/bin/foundry generate admin-resource  --json
php vendor/bin/foundry generate uploads avatar --json
php vendor/bin/foundry generate uploads attachments --json
php vendor/bin/foundry generate notification  --json
php vendor/bin/foundry generate api-resource  --definition= --json
php vendor/bin/foundry generate docs --format=markdown --json
php vendor/bin/foundry generate docs --format=html --json
php vendor/bin/foundry generate indexes --json
php vendor/bin/foundry generate tests  --json
php vendor/bin/foundry generate tests  --mode=deep --json
php vendor/bin/foundry generate tests --all-missing --mode=deep --json
php vendor/bin/foundry generate migration  --json
php vendor/bin/foundry generate context  --json
```

Export:

```
php vendor/bin/foundry export openapi --format=json --json
php vendor/bin/foundry export openapi --format=yaml --json
```

Verify:

```
php vendor/bin/foundry verify feature  --json
php vendor/bin/foundry verify graph --json
php vendor/bin/foundry verify pipeline --json
php vendor/bin/foundry verify extensions --json
php vendor/bin/foundry verify compatibility --json
php vendor/bin/foundry verify contracts --json
php vendor/bin/foundry verify auth --json
php vendor/bin/foundry verify cache --json
php vendor/bin/foundry verify events --json
php vendor/bin/foundry verify jobs --json
php vendor/bin/foundry verify migrations --json
php vendor/bin/foundry verify resource  --json
php vendor/bin/foundry verify notifications --json
php vendor/bin/foundry verify api --json
```

Runtime / planning:

```
php vendor/bin/foundry init app  [--name=vendor/app] [--version=^0.1] [--force]
php vendor/bin/foundry serve
php vendor/bin/foundry queue:work
php vendor/bin/foundry queue:inspect --json
php vendor/bin/foundry schedule:run --json
php vendor/bin/foundry trace:tail --json
php vendor/bin/foundry affected-files  --json
php vendor/bin/foundry impacted-features  --json
php vendor/bin/foundry migrate definitions --dry-run --json
php vendor/bin/foundry migrate definitions --path= --dry-run --json
php vendor/bin/foundry migrate definitions --write --json
php vendor/bin/foundry codemod run  --dry-run --json
php vendor/bin/foundry codemod run  --write --json
```

Tests
-----

[](#tests)

Test suite includes unit and integration coverage for:

- parsing/validation/generation/verification
- CLI JSON command behavior
- HTTP feature execution pipeline
- DB query execution
- queue/event/cache/webhook/AI subsystems
- example app structure checks

Run:

```
vendor/bin/phpunit
```

Optional local integration targets:

- Redis queue integration tests run when `ext-redis` is loaded and Redis is reachable on `127.0.0.1:6379`.
- PostgreSQL integration tests run when `pdo_pgsql` is loaded and Postgres is reachable.
- MinIO storage integrations can use `Foundry\Storage\MinioStorageDriver` with an injected client, or with `aws/aws-sdk-php`.
- MinIO integration test env overrides: `FOUNDRY_TEST_MINIO_ENDPOINT`, `FOUNDRY_TEST_MINIO_ACCESS_KEY`, `FOUNDRY_TEST_MINIO_SECRET_KEY`, `FOUNDRY_TEST_MINIO_BUCKET`, `FOUNDRY_TEST_MINIO_REGION`.
- PostgreSQL DSN/user/pass can be overridden with: `FOUNDRY_TEST_PG_DSN`, `FOUNDRY_TEST_PG_USER`, `FOUNDRY_TEST_PG_PASS`.
- If `postgresql@17` is keg-only on Homebrew, use: `/opt/homebrew/opt/postgresql@17/bin/psql`and optionally add it to `PATH`.

Coverage note:

- code coverage output requires a coverage driver (`xdebug` or `pcov`).
- if not installed, tests still run but coverage metrics are unavailable.
- when Xdebug is installed but not auto-loaded in CLI, run coverage with: `php -dzend_extension=/path/to/xdebug.so -d xdebug.mode=coverage vendor/bin/phpunit --coverage-text`

Examples
--------

[](#examples)

Included example apps:

- `examples/blog-api`
- `examples/dashboard`
- `examples/ai-pipeline`
- `examples/compiler-core`
- `examples/extensions-migrations`
- `examples/architecture-tools`
- `examples/execution-pipeline`
- `examples/app-scaffolding`

Each example includes feature folders plus generated indexes.

Additional Docs
---------------

[](#additional-docs)

- `ARCHITECTURE.md`
- `FEATURE_DEFINITION.md`
- `BENCHMARK_NOTES.md`
- `docs/semantic-compiler.md`
- `docs/extensions-and-migrations.md`
- `docs/architecture-tools.md`
- `docs/execution-pipeline.md`
- `docs/app-scaffolding.md`
- `docs/api-notifications-docs.md`
- `docs/contributor-vocabulary.md`

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance100

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity47

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

8

Last Release

1d ago

PHP version history (2 changes)v0.1.0PHP ^8.5

v0.2.1PHP ^8.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/81647167603b91be4eb9cbb77f4dd59704b1dfb7d00095a03de01fafb8716486?d=identicon)[lo\_fye](/maintainers/lo_fye)

---

Top Contributors

[![lofye](https://avatars.githubusercontent.com/u/56428?v=4)](https://github.com/lofye "lofye (24 commits)")

---

Tags

llmphp84webframework

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/lofye-foundry-framework/health.svg)

```
[![Health](https://phpackages.com/badges/lofye-foundry-framework/health.svg)](https://phpackages.com/packages/lofye-foundry-framework)
```

###  Alternatives

[akeneo/pim-community-dev

Akeneo PIM, the future of catalog management is open!

1.0k610.8k78](/packages/akeneo-pim-community-dev)[cpsit/project-builder

Composer package to create new projects from project templates

2536.4k](/packages/cpsit-project-builder)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)
