README

A self-contained, embeddable web IDE delivered as a single PSR-15 middleware plus a dependency-free SPA. Codiware is designed to be mounted under an arbitrary base path inside any PHP host application (e.g. the ExFace workbench) and operate on a configurable set of workspace folders.

Features

File tree, multi-tab editor, save / rename / delete / upload / download
Pluggable editor registry (textarea fallback included; Monaco, CodeMirror, Toast UI, etc. can be plugged in via npm-asset packages or custom JS)
Git source-control panel (status, stage / unstage / discard, commit, amend, push, branches, history) over the local git CLI
Workspace-wide search and search-and-replace with regex / case options
In-IDE console with a deny-by-default allowlist + operator-curated presets
Light/dark themes via CSS custom properties; per-locale translations
All paths protected by a single PathGuard that rejects traversal, symlink escape, and matches configurable deny patterns (.env, *.key, …)

Requirements

PHP 8.2+
Composer
Optional: a local git binary for the source-control panel

Install

composer require axenox/codiware

The package depends on npm-asset/* packages for optional front-end editors. The composer.json already enables Asset Packagist so npm-asset/monaco-editor and friends can be installed alongside PHP packages.

Mount in a host

use kabachello\Codiware\Middleware\CodiwareMiddleware;
use kabachello\Codiware\Middleware\CodiwareConfig;
use kabachello\Codiware\Middleware\UserContext;

$middleware = new CodiwareMiddleware(
    config: CodiwareConfig::fromFile(__DIR__ . '/codiware.json'),
    responseFactory: $psr17,
    streamFactory: $psr17,
    logger: $psrLogger,
    userContext: new UserContext($user->getName(), $user->getEmail(), $user->getId())
);

CodiwareMiddleware implements Psr\Http\Server\MiddlewareInterface. Any request whose URI path is not under the configured base path is delegated unchanged to the next handler.

Workspace URL

GET {basePath}/repo/{workspacePath...} returns the SPA shell with a boot payload describing the requested workspace, user, theme, locale, and enabled extensions. All subsequent API calls go to other {basePath}/... routes.

Configuration

Defaults are shipped in config/defaults.config.json.

At runtime, CodiwareConfig behaves like ExFace config maps:

keys are normalized to uppercase
nested objects are flattened to dot keys (CONSOLE.ENABLED)
arrays and arrays of objects stay as values (CONSOLE.PRESETS)

See dev-server.config.json.example for a documented sample.

Typical host override patterns:

$config = CodiwareConfig::fromFile(__DIR__ . '/codiware.json')
  ->set('URL_TO_API', '/api/ide/codiware')
  ->merge([
    'THEME.DEFAULT' => 'dark',
    'CONSOLE.TIMEOUT_SECONDS' => 120,
  ]);

Key options:

Key	Purpose
`URL_TO_API`	URL prefix the middleware listens on (default `/codiware`).
`BASE_FOLDER`	Folder whose direct children are valid workspace aliases.
`ALLOWED_ROOTS`	Explicit `[{alias, path, label}]` list overriding `BASE_FOLDER`.
`DENY_PATTERNS`	`fnmatch` patterns rejected by `PathGuard`.
`MAX_UPLOAD_BYTES`	Per-file upload limit.
`GIT.BINARY`	Path to the `git` executable.
`CONSOLE.ALLOW_PATTERNS`	Regex allowlist for raw console commands.
`CONSOLE.PRESETS`	`[{label, command}]` shortcuts always allowed.
`THEME.DEFAULT`	`light` or `dark`.
`TRANSLATIONS.DEFAULT_LOCALE`	Initial UI locale.
`EXTENSIONS.ENABLED`	Identifiers of front-end extensions to load.

Development server

composer install
cp dev-server.config.json.example dev-server.config.json
php -S localhost:8080 -t public public/dev-server.php

Open http://localhost:8080/codiware/repo/{workspace-alias}.

Extending the editor

The SPA exposes a small global API on window.Codiware:

window.Codiware.registerEditor({
    id: 'my.editor',
    label: 'My editor',
    priority: 50,
    accepts: (entry) => /\.json$/i.test(entry.path),
    create: (host, ctx) => new MyEditor(host, ctx),
});

Each editor implements load(content, meta), getContent(), isDirty(), markClean(), destroy(), and an optional on('change'|'save-request', fn).

Adding a richer editor library (Monaco, CodeMirror 6, Toast UI):

composer require npm-asset/monaco-editor (or similar)
Drop a small JS module under public/js/extensions/ that imports the library from /{basePath}/assets/monaco-editor/... and calls window.Codiware.registerEditor(...).
Add the extension id to EXTENSIONS.ENABLED in the config — the SPA boot payload exposes the list so your extension knows it is enabled.

Security model

All filesystem paths flow through kabachello\Codiware\Workspace\PathGuard, which resolves them via realpath, rejects .. traversal and any path that ends up outside the workspace root, and matches the configured deny patterns against both the relative path and the basename.
Uploaded ZIP archives are fully validated entry-by-entry (rejects absolute paths, ../, and runs every resolved destination through PathGuard) to prevent zip-slip.
Console commands are deny-by-default. A command runs only if it matches a preset label or a configured regex in CONSOLE.ALLOW_PATTERNS.
The middleware never trusts the host with raw paths: workspace selection always goes through WorkspaceResolver which validates against ALLOWED_ROOTS / BASE_FOLDER first.

License

MIT. See LICENSE.

kabachello / codiware

Maintainers

Package info

Statistics

Security