Ariel

The official VS Code extension for the Ariel Framework.

Ariel for VS Code is a thin IDE layer over the existing Ariel CLI. It does not contain framework generators and does not copy private Ariel implementation code. Generation/build actions are delegated to commands provided by the project-local php ariel executable.

Framework compatibility

The extension reads FRAMEWORK_VERSION from the Ariel project's .env.development and exposes only commands supported by that framework version. The compatibility matrix is based on the historical BaseMVC/Ariel release tags.

Important milestones used by the extension include:

• Ariel 4: Model, Controller, Schema, Migration, Seeder, Enum, Console, Messenger, Swagger and HTTP generation.
• Ariel 5: Server and Router generation.
• Ariel 6: Service, Agent, routes and base cache tooling.
• Ariel 7: modern development tooling including docs, tests, Queue, Socket events, Isolates, Options, DTO/WSDL and validation generation.
• Ariel 7.1: Backup.
• Ariel 7.2.3: make:models and Sync.
• Ariel 7.3: Advisors, Scheduler, Mail Actions and newer runtime tooling.
• Ariel 8: Model --crud, deterministic Controller generation from Model/Service, HTTP/Pre-Ariel cache controls and other v8-only capabilities.

Projects without FRAMEWORK_VERSION are treated conservatively as legacy/unknown instead of exposing commands that may not exist.

Models and Services

Right-click app/Models or app/Services (including subfolders) to use their matching Ariel generators. Version and nested directory are inferred from versioned paths.

On Ariel 8+, Model files show Make missing CRUD. Model and Service classes also show Make Controller, which delegates to Ariel's --from-model / --from-service support.

Controllers

Controller classes expose version-compatible Router and Swagger generation actions.

When a Controller response contract uses an inline JSON string, the extension exposes Edit JSON Return on that metadata. It supports both the legacy form #[ReturnType(type: '...')] and the modern #[Method(return: '...')]. Schema classes, Types::..., arrays of schemas and null are ignored. The editor pretty-prints the JSON, validates it before applying, and writes it back as a compact PHP string.

Every public static route that already has #[Method] exposes Test Endpoint directly above that Method attribute. It resolves the generated .http request by Controller Tag + method name and sends that request, reusing generated query/body variables and authentication data. If the HTTP file or named request is missing, the extension first runs php ariel generate:http -a <version>, waits for generation to finish, and then retries automatically.

For missing route metadata, the extension exposes one CodeLens per missing attribute found in the installed framework's own UserController, such as Add Method, Add Param, Add Uses, Add ReturnType and access metadata on legacy versions. Historical projects use app/Controllers/V1/UserController.php; the current Ariel layout prefers app/Controllers/V1/Common/UserController.php. Method is always kept first, regardless of the order in which attributes are added. The extension derives placeholder shape and attribute order from that file instead of embedding Ariel 4/5/7/8 attribute contracts in TypeScript.

Schemas

Each promoted Schema property has a CodeLens row above its block. If a contiguous #[Property(...)] attribute exists, the controls are placed above the attribute so the attribute and declaration remain visually grouped.

The state action alternates between Make nullable and Make required:

#[Property(description: 'Name')]
public string $name,

can become:

#[Property(description: 'Name')]
public ?string $name = null,

and Make required removes nullable typing plus the default value again. Union types use/remove |null as appropriate.

The same CodeLens row also exposes ↑ Move up and ↓ Move down where possible. Moving a property treats its contiguous PHP attributes (including #[Property]) and the promoted property declaration as one block, so they can never be separated accidentally.

Automatic generation on save

With ariel.generateOnSave enabled (default), saving a versioned Controller or Schema automatically rebuilds the generated Ariel artifacts for that API version.

Compatibility follows the framework version reported by .env.development:

• before Ariel 7.3.0: saving a Controller runs generate:router -a <version>; saving a Schema runs generate:swagger -a <version>.
• Ariel 7.3.0 and newer: saving either a Controller or a Schema runs both generate:router -a <version> and generate:swagger -a <version>.

Rapid saves are debounced and merged per Ariel root/API version. Generation runs in the background, shows status in the VS Code status bar, and exposes the Ariel output when a generator fails. Only generators supported by the detected Ariel version are executed.

HTTP client

Ariel includes its own lightweight client for the generated .http files, so the standard Ariel workflow does not require REST Client.

At the top of each .http file, Update HTTP delegates to php ariel generate:http. Each generated request receives a Send Request CodeLens.

The client currently supports the Ariel generated format:

• @variable = value;
• {{variable}} substitution;
• ### @name ...;
• GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS;
• headers;
• JSON and form-urlencoded bodies;
• redirects;
• configurable timeout;
• formatted JSON responses.

The response opens beside the request with status, elapsed time, headers and body. Advanced REST Client-specific features such as multipart file macros, cookie jars and scripting are not emulated unless Ariel's generated format needs them.

Console

Files under app/Console expose Run Console Command directly above run().

Migrations

Create migrations containing Schema::create(...) can create their Model while reusing the table automatically. Migration context also exposes compatible Model(s), Enum, Seeder and Migrate + Seed actions.

Nest refactor

Select one or more PHP files in the same Ariel app/** folder and use Ariel → Nest.... Enter a PHP-safe subfolder such as Auth or Domain/Auth.

Before applying anything, the extension shows a modal preview with moved files and reference counts. When confirmed it:

• moves the selected files into the requested subfolder;
• appends that folder to each selected file's PHP namespace;
• updates explicit use statements and fully-qualified class names across PHP files in the containing VS Code workspace;
• asks the active PHP language provider for semantic references so unqualified same-namespace usages can also be rewritten safely;
• keeps short-name references unchanged when both referenced and referencing files move together into the same new namespace.

If no PHP semantic reference provider is available for a selected symbol, the preview warns about the limitation before applying. Explicit namespace/use/FQCN updates still work, but unqualified references may then require manual review.

Multi-selection is supported through the Explorer context menu. All selected files must belong to the same Ariel root, folder and namespace.

Ariel → Unnest... is the inverse operation and moves the selected files up exactly one folder level while applying the same namespace/reference updates and preview. It refuses to cross a logical/version root (for example app/Models/V1/User.php cannot be unnested to app/Models/User.php). When the source nested folder becomes empty after the move, the extension removes it automatically.

Project menus

The Explorer's Ariel menu is available on Ariel files as well as folders and is grouped instead of presenting one large flat list:

• Create
• Generate
• Run & Test
• Advisors
• Cache

Folder-specific actions are shown on Models, Services, Controllers, Schemas, Enums, Console, Messengers, Queues, Sockets, Servers, Schedules, MailActions, Agents, Isolates, Options and migration/seeder folders where supported by the detected Ariel version.

The root-oriented menu includes useful generators rather than every CLI command. Tests run as php ariel test --stan without --core.

Ariel 7.3+ exposes Architecture, Database, Eloquent, Performance, Security and Penetration advisors in the Advisors submenu. Cache menus are version-gated, including the v8 HTTP Response Cache and Pre-Ariel Cache commands.

Documentation shortcut

On Ariel versions that provide php ariel doc, PHP files inside the Ariel root show Ariel Docs near the top of the file.

Nested workspaces

Ariel may live inside a larger repository, for example:

project/
├── frontend/
└── api/
    ├── ariel
    ├── composer.json
    ├── app/
    └── config/

The extension detects the directory containing ariel, validates the Ariel structure, and scopes framework commands to that root. Frontend files do not become Ariel generator targets. Multiple Ariel roots are supported.

Docker actions begin at the detected Ariel root and walk upward inside the containing VS Code workspace to locate the nearest Compose file.

Localization

English is the source/default language. Italian translations are included. VS Code automatically selects the installed display language and falls back to English when a translation is unavailable.

Settings

Development

Run npm install, then npm run check, npm test, and npm run package. Press F5 in VS Code to launch an Extension Development Host.

Architecture rule

The extension may detect Ariel projects and versions, inspect source to offer editor refactors, collect user input, and invoke project-local Ariel/Docker commands. It must not implement Ariel's framework generators itself.

Swagger attribute insertion is source-driven rather than hard-coded. Missing method attributes are discovered and templated from the installed Ariel project's own UserController, which keeps legacy and current projects aligned without shipping private Ariel attribute contracts inside the public extension.