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.
Model classes also expose editor productivity actions:
- Generate fillable appears only when a Model declares
protected $table and has no $fillable. It opens a VS Code input where field names can be pasted with comma, semicolon or newline separators. MySQL/phpMyAdmin quotes and backticks are removed, duplicates are collapsed, and the resulting fields are emitted as a normal single-quoted PHP fillable array. Submitting an empty/blank input creates protected $fillable = [];. The extension intentionally does not read DB credentials or open its own database connection.
- Create relation asks first for the relation method name, then the Eloquent relation type, and finally (when needed) lets you choose an existing Model from
app/Models/**. The extension adds the related Model use automatically and uses the short class name in the relation body when no import conflict exists.
belongsToMany additionally asks for the pivot table name. The pivot table does not need its own Model; editable key placeholders such as model_id and related_id remain visible in the generated call.
- Relation choices include
belongsTo, hasOne, hasMany, belongsToMany and the polymorphic relations recognized by Ariel's Eloquent tooling.
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.
Controller classes with missing standard CRUD methods also expose Create CRUD functions. The multi-select picker shows only missing index, show, add, edit, and del methods. Signatures and method attributes are read from the installed project's resolved UserController (preferring app/Controllers/V1/Common/UserController.php on v8, then historical locations). Generated methods have empty bodies; route/schema/filter-specific values are replaced with source-driven placeholders while structural enum values such as HTTP method, parameter position, input type and primitive type remain aligned with the reference method.
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 Clone, ↑, Move, and ↓. Clone asks for a new property name, preserves the promoted property's type/nullable/default state, and creates a fresh #[Property(description: '<newName>')] instead of copying the original Property metadata. Move opens a Move after: property picker for arbitrary reordering; the arrow controls remain available for one-step movement. Every move treats contiguous PHP attributes (including multiline #[Property(...)]) and the promoted property declaration as one indivisible block.
Automatic generation on save
With ariel.generateOnSave enabled (default), saving a versioned Controller or Schema automatically rebuilds the generated Ariel artifacts.
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.x: saving either a Controller or a Schema runs both
generate:router -a <version> and generate:swagger -a <version>.
- Ariel v8+: saving a Schema runs
php ariel compile (project-wide, no -a); saving a Controller runs php ariel generate:router -a <version> followed by php ariel generate:swagger -a <version>.
Rapid saves are debounced. v8 Schema saves across API versions share one project-wide compile batch; Controller rebuilds remain API-version-scoped. All commands are serialized per Ariel project to avoid collisions. Generation runs in the background, shows status in the VS Code status bar, and exposes the Ariel output on failure.
v8 prerequisite: the installed Ariel CLI must actually register the compile command. Older v8 builds still exposing only generate:validation must be updated to a framework revision providing php ariel compile; the extension does not silently substitute a different command.
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.
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
| Setting |
Default |
Purpose |
ariel.phpExecutable |
php |
PHP executable used for Ariel CLI commands. |
ariel.dockerCommand |
docker compose |
Docker Compose command used by Docker Up/Down. |
ariel.reuseTerminal |
true |
Reuse one Ariel terminal per detected project root. |
ariel.httpTimeoutMs |
30000 |
Timeout for requests sent by the built-in HTTP client. |
ariel.generateOnSave |
true |
Rebuild version-compatible Router/Swagger artifacts after saving Controllers or Schemas. |
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.