remi-san / minipavi-service
Framework for Minitel services on MiniPavi: XML pages and templates, controllers, routing
Requires
- php: >=8.2
- ext-mbstring: *
- ext-simplexml: *
- ludosevilla/minipavi-cli: ^1.1.1
- nyholm/psr7: ^1.8
- nyholm/psr7-server: ^1.1
- psr/http-message: ^2.0
- psr/http-server-handler: ^1.0
- psr/log: ^3.0
- symfony/console: ^7.1
Requires (Dev)
- carthage-software/mago: ^1.60
- phpunit/phpunit: ^11.5
Suggests
- monolog/monolog: A PSR-3 logger for the service, e.g. to PHP's error log (ErrorLogHandler)
- phpunit/phpunit: For Testing\ServiceTester, functional tests of a service (^11.5)
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.1.0
- dev-fix/30-zone-background-masking
- dev-test/66-vdt-parser-sequences
- dev-test/57-vdt-screen-tests
- dev-chore/86-approval-label
- dev-chore/84-tester-agent
- dev-fix/61-guard-fallbacks
- dev-chore/81-agents-workflow
- dev-test/60-layers
- dev-fix/59-int-leading-zeros
- dev-test/68-trusted-proxies-and-scheme
- dev-fix/6-constant-log-messages
- dev-chore/74-minimum-msi
- dev-chore/64-coverage-minimum-and-mutation-testing
- dev-refactor/46-lint-baseline
This package is auto-updated.
Last update: 2026-11-19 22:12:43 UTC
README
PHP framework for Minitel services behind a MiniPavi gateway. It builds on the
official ludosevilla/minipavi-cli.
- Pages described in XML: static, or templates with placeholders, loops and conditions
- Controllers, one per screen, each a small state machine returning responses
- A router and a context keeping each controller's state between requests
- A service without I/O: it responds to a
GatewayRequestwith aGatewayResponse, whichMiniPaviClientreads from and sends to the gateway, through the staticMiniPaviCli Vdt, to read Videotex content (e.g. pictures made with a Videotex editor) and move it on the screen
Requires PHP 8.2.
The code (namespace MiniPaviService, in src/) is organized by layer, each using only those
below it (mago guard checks it, with the rules in mago.toml). At the bottom, the helpers
(Text\, Io\, Xml\, Html\, InvalidValueException), then Minitel\ (the terminal),
then Vdt\ (Videotex), then Gateway\ (the requests, responses and commands); Message\
beside them. Above them, Page\ → Controller\ → Core\ (the runtime) → Http\ (the
entry point), which also uses Client\ (the clients, on Gateway\). Cli\ (on Page\)
and Testing\ (on Core\) sit on top. The one exception: Minitel\Key names
Gateway\ConnectionCode (#49 removes it).
| Namespace | Holds |
|---|---|
MiniPaviService |
the Controller and Page interfaces, and the InvalidValueException of a value the framework can't take (e.g. a Position off the screen) |
Core\ |
the runtime: Service, Router and its Routes, Context and its RouteContexts, RequestFlow |
Controller\ |
AbstractController, Request, Response and the response types, Flow, the states (State, ControllerState) |
Controller\Parameters\ |
what a controller keeps: Parameters, NoParameters, their ParametersType (what Controller::parametersType() returns), and the raw Values they are read from |
Controller\Pagination\ |
PaginatedController, the PaginatedList it shows and its ShownPage, Paginator, PageParameters |
Page\ |
static and template pages, their display elements, and the page XML parser |
Message\ |
the messages shown on screen: Message, FrameworkMessage, Messages and their XML parser |
Minitel\ |
the user's terminal: Terminal, its FunctionKeys, its settings (Keyboard, LocalEcho, Scroll), its ScreenSize and Colors, and the InputField where the user types |
Vdt\ |
Videotex: codes, reading, writing and moving Videotex content (Vdt, Videotex); in Screen\, the Minitel screen it draws (Screen, Cell) and its HTML rendering (HtmlRenderer) |
Gateway\ |
the requests and responses the service handles (GatewayRequest, GatewayResponse), the commands a response sends (Command: the WaitForKeyCommand waiting for a key, the InputCommand reading a field, the ServiceCallCommand calling a service, with its CallMode), and the Client interface reading and sending them |
Client\ |
the clients: MiniPaviClient for the MiniPavi gateway, HtmlClient for a browser (?web=true) |
Http\ |
the entry point for the web server, on PSR-7 / PSR-15: Kernel, ResponseEmitter, ServiceRunner; in Dispatch\, who handles the request (Dispatcher, ConditionalRequestHandler, RequestMatchers); in Url\, the request's URLs (RequestUrl, UrlAttribute, WithUrls); in Emulator\, the emulator browsers are sent to (EmulatorConfig, EmulatorRedirect) |
Testing\ |
ServiceTester, functional tests of a service (needs PHPUnit) |
Installing
From Packagist, at its main
branch (or a release, e.g. ^0.1):
{
"require": { "remi-san/minipavi-service": "dev-main" }
}
To work on the framework and a service together, point the service at a local clone with a
path repository (Composer symlinks it into vendor/, so edits to the framework apply without
reinstalling), and don't commit it:
{
"repositories": [{ "type": "path", "url": "../minipavi-service" }]
}
The skeleton, remi-san/minipavi-service-skeleton, uses it this way.
Writing a service
public/index.php builds the pages and controllers, and hands them to the service:
use Monolog\Handler\ErrorLogHandler; use Monolog\Logger; use MiniPaviService\Core\RouterBuilder; use MiniPaviService\Http\Emulator\EmulatorConfig; use MiniPaviService\Http\KernelBuilder; use MiniPaviService\Http\Url\RequestUrl; use MiniPaviService\Message\MessagesXmlParser; use MiniPaviService\Page\Parser\PageXmlParser; require __DIR__.'/../vendor/autoload.php'; // The framework's messages; a service usually reads its own over them (see Messages) $messages = (new MessagesXmlParser())->defaults(); // New connections start at the default route; build() fails if it isn't one of the routes $router = (new RouterBuilder(HomeController::NAME)) ->addRoute(HomeController::NAME, new HomeController((new PageXmlParser($messages))->parseFile(__DIR__.'/../config/pages/home.xml'))) ->build(); // The environment is read here (or in the container): the framework doesn't read it itself KernelBuilder::for($router, $messages) ->withLogger(new Logger('my-service', [new ErrorLogHandler()])) // Monolog ->withContextKey(getenv('CONTEXT_SECRET') ?: '') ->withRequestUrl(new RequestUrl(getenv('SERVICE_URL') ?: null, getenv('TRUSTED_PROXIES') ?: '')) ->withEmulator(EmulatorConfig::fromValues(getenv('EMULATOR_URL') ?: null, getenv('GATEWAY_URL') ?: null, getenv('SERVICES_INTERNAL_HOST') ?: null)) ->build() ->run();
-
Http\KernelBuilderbuilds theKernelwith the framework's wiring, described below: aServicefor the router and messages; the gateway's requests run it withMiniPaviClient, browsers asking?web=truewithHtmlClient, the others are sent to the emulator (EmulatorRedirect); the URLs are computed byWithUrls, the request created withnyholm/psr7-server. It is immutable: eachwith...()gives a builder changing one thing. What a service doesn't give has a default:withLogger(): where every part logs (default: nowhere);withContextKey(): the key signing the context (HmacContextSigner); without it, or with'', the context isn't signed, and a warning is logged on each request;withRequestUrl(): how the service's URLs are computed (default: the request's);withEmulator(): where browsers are sent (default: the minipavi.fr emulator and gateway);withHandler(): aConditionalRequestHandlerof the service (e.g. an API, a health check), tried before the framework's, in the order they are added;withMaxPageChanges(): the page changes allowed in one request (default: 10, see below; 0 forbids them; a negative number makesbuild()throw anInvalidValueException);withFont(): the TrueType font of the HTML client's screen (default: the framework's Minitel font,HtmlRenderer::MINITEL_FONT); a file that can't be read throws anInvalidValueExceptionthere, rather than on each browser's request.
A service needing another wiring builds the
Kernelitself, from the classes below. -
Lazy controllers: a service with many screens shouldn't build every controller, and parse every page, on each request. With a dependency injection container such as PHP-DI, define the controllers as lazy: the router gets proxies, and a controller is only built when its route runs (PHP 8.4's native lazy objects, which keep controllers
final). See theconfig/container.phpof the skeleton:$container = (new ContainerBuilder())->addDefinitions([ 'page.home' => factory([PageXmlParser::class, 'parseFile'])->parameter('file', "$config/pages/home.xml"), 'controller.home' => create(HomeController::class)->constructor(get('page.home'))->lazy(), RouterBuilder::class => create() ->constructor(HomeController::NAME) ->method('addRoute', HomeController::NAME, get('controller.home')), Router::class => factory([RouterBuilder::class, 'build']), ])->build(); $router = $container->get(Router::class);
-
Kernelis whatpublic/index.phpruns, and the only place reading the globals: it creates the PSR-7 request from the globals with the creator it is given (e.g.nyholm/psr7-server'sServerRequestCreator, withnyholm/psr7's PSR-17 factories), has its handler (PSR-15) handle it, and sends the response withResponseEmitter(its status, headers and body): every response, the gateway's included. No other class reads$_SERVER, the environment or the request's body, nor writes headers or output (whatMiniPaviCliwrites for the gateway is captured, below). -
WithUrlscomputes the service's URLs for the request once, withRequestUrl, and passes it on with them in its attributes (UrlAttribute):Service, the script, given to the gateway as the next URL to call (the client keeps it with the request it reads), andCurrent, the URL asked for, where the emulator sends browsers back.RequestUrltakes https when the request came over TLS (HTTPS, port 443), and its configuration explicitly (read from the environment in the service's container):SERVICE_URL(e.g.https://minitel.example.org): scheme and host to use instead of the request's;TRUSTED_PROXIES(e.g.10.0.0.1, 172.16.0.0/12): reverse proxies whoseX-Forwarded-Protois believed, when they terminate TLS. From anyone else, the header is ignored.
-
Dispatch\Dispatcherdecides who the HTTP request is for: the first of its **ConditionalRequestHandler**s matching the request (a list, tried in its order), or else its fallback. AConditionalRequestHandleris a PSR-15 handler with a name and a condition (RequestMatcher); the framework's matchers areFromMiniPaviGateway(User-AgentwithMiniPAVI) andQueryParameterEquals(e.g.web=true, that value only). The services send the gateway's requests to aServiceRunnerwithMiniPaviClient, browsers asking?web=trueto one withHtmlClient, and other browsers to the fallback,EmulatorRedirect. A service adds its own (e.g. an API, a health check) with its own matchers. TheDispatcherlogs the handler of each request, at debug level. -
ServiceRunnerruns the service for an HTTP request, through a client (Gateway\Client, inClient\) translating between HTTP and the service's values: the client reads the HTTP request into aGateway\ClientExchange(exchange()), whoserequest()the service responds to, and whoserespond()turns theGatewayResponseinto the HTTP response. What the client needs to respond, besides what the service gets (the service's URL, the pageHtmlClient's browser showed), stays in the exchange. A request that can't be read gets an error as its response (seeService), through the client'sunreadable()exchange; nothing to respond to (a disconnection, a background call of the gateway) is a204, and a response the client can't give (or anunreadable()exchange it can't give) a500(logged as critical). The context is signed on its way through the gateway (or the browser), so that the user can't change it: anyone could otherwise send another route, or other parameters.Servicetakes itsCore\ContextSerializer(KernelBuildergives it), which signs the context of each response and checks the one of each request it reads with aCore\Signing\ContextSigner(that of a connection, a disconnection or a background call isn't read, so it isn't checked).HmacContextSignersigns it with an HMAC-SHA256 of a secret key (<signature>.<context>),UnsignedContextdoesn't. A context the signer didn't sign (ForgedContextException) is responded to as one that can't be read. Keep the key out of the repository: the services read it from the environment,CONTEXT_SECRET(openssl rand -base64 32), and don't sign the context without it, with a warning. Changing the key makes the users of sessions in progress start again at the default route. A serializer without signer (new ContextSerializer($router), e.g. for aServiceTester) doesn't sign it (UnsignedContext). Two clients:-
MiniPaviClient, for the MiniPavi gateway, throughMiniPaviCliused unchanged: it reads the gateway's request itself (background calls included, which the service doesn't respond to), and writes the response itself:MiniPaviClientcaptures it as the body of the HTTP response. It is the only class callingMiniPaviCli, besidesVdt's Videotex helpers: its exchange and the commands it sends go through it; -
HtmlClient, for a browser: it shows the service's screen as an HTML page (Vdt\Screen\HtmlRenderer), and lets the user navigate it as on a Minitel. The first request is a connection, at the default route, as the gateway's. The page is a form posting back to its URL, whichClient\HtmlFormrenders and reads back (PostedForm),HtmlClientturning it into aGatewayRequest, and a response into the page:- the response's input field (the
InputFieldof itsInputCommand: a text field, or a message of several lines) over the screen, at its position and size, one input per line; - the 8 function keys under the screen, in the Minitel's 2 × 4 layout, those the
input doesn't accept (
validwith) disabled; Enter in a field presses Envoi; - hidden, the context of the response, its input command (as JSON,
Client\InputCommandJson), and the screen so far: a response drawing part of the screen (e.g. "Dernière page" on line 0) is drawn over it, as on a Minitel (kept from its last clear screen). The page's screen and command come back with the key as the client's state (HtmlPageState).
A key that would leave the service (a response calling another service, a
ServiceCallCommand, asRunCommand::connectTo()gives) is blocked: the page stays as it was, withFrameworkMessage::WebLeaveon line 0. The key labels and that error are messages (key.send,key.next…,web.leave). The screen is drawn in the Minitel's colours, with double sizes, inverse video, underlining, blinking and mosaic pixels, as MiniPavi's emulator does, in self-contained HTML (inline CSS, no JavaScript). The text is drawn with the Minitel font of Minitel-Canvas (CC0, inresources/fonts), embedded in the page (HtmlRenderer::MINITEL_FONT, read for each page only: the gateway's requests don't need it). - the response's input field (the
-
-
EmulatorRedirectsends other browsers to an emulator that opens the service (EmulatorConfig): with an emulator configured (EMULATOR_URL, the local stack), that emulator and the gatewayGATEWAY_URL, which reaches the service atSERVICES_INTERNAL_HOST; otherwise (a public server), the minipavi.fr emulator and gateway, with the URL the browser asked for.EmulatorConfig::fromValues()takes those values, read from the environment in the service's container. -
Serviceresponds to a request of the gateway, without I/O:$service->handle(GatewayRequest): ?GatewayResponse(null for a disconnection or a background call of the gateway,BGCALL-WM-..., which have nothing to respond to). It restores theContext, and runs the controller of the current route until a response responds to the gateway.Serviceowns the context: a response says, through aFlow(see below), the state and parameters its controller keeps and what comes next. A context without route starts at the default route. One whose route the service doesn't have (e.g. removed in a new version) starts again there too, without what the user typed, which was for a screen that doesn't exist any more (the serializer refuses it with anUnknownRouteException). More than 10 page changes (ChangePage) in one request are taken as controllers changing to each other endlessly, and responded to with an error; give another limit withKernelBuilder::withMaxPageChanges(20)(ornew Service(..., maxPageChanges: 20)), 0 to forbid page changes. If serving a request fails (an exception or a PHP error, in a controller, a template, the context...), the error is logged, and the user gets a message on line 0 (FrameworkMessage::Error, from the$messagesof the constructor; see Messages): their next function key starts again at the default route. -
GatewayRequestis what the gateway sends:key(aMinitel\Key: aFunctionKeyor aConnectionCode, which itsfunctionKey()andconnectionCode()tell apart, or null for another key;GatewayRequest::keyOf()reads it from what the gateway sends,fctn()gives its name back),content(the text typed),context(given back from the previous response) andterminal.GatewayResponseis what is sent back:vdt,contextandcommand, what the gateway does next (aGateway\Command: aWaitForKeyCommand, the default, waiting for a key, then calling this service; anInputCommandreading a field; aServiceCallCommandcalling a service at once, with its URL andCallMode). Each client sends a command its own way, with itsGateway\CommandSender, whose method for it the command calls (Command::sendWith()). The commands are the framework's: a service sends them, but can't add one, since its clients wouldn't know it. The framework adds a command as a class implementingCommandand a method ofCommandSender, so that a client that doesn't send it can't be loaded. Both are plain values, so a service can be tested, or run elsewhere than PHP's web server, withoutMiniPaviCli. -
Pages are displayed for the user's terminal, which
<endkey>depends on:$page->display($request->terminal(), $data); display elements get it too (Element::toVdt(Terminal $terminal): Vdt). -
Logging:
Service,ServiceRunner,DispatcherandEmulatorRedirecttake an optional PSR-3 logger (KernelBuilder::withLogger()gives it to all of them; e.g. Monolog, with itsErrorLogHandlerfor PHP's error log, as the skeleton does) and log connections, disconnections and browsers sent to the emulator at info level, the handler of each request at debug level, and errors at error level. Each message is always the same, what varies being in its context (the exception, the function key, the route...), so that a log analyzer can group them:new Service($router, $messages, $serializer, logger: $logger),new ServiceRunner($service, $client, $logger),new Dispatcher($handlers, $fallback, $logger),new EmulatorRedirect($emulator, $logger). Without one, nothing is logged. -
A
Controllerruns on aRequestand returns aResponse. The request gives:state()andparameters(): what the controller's previous response asked to keep, from one request of the gateway to the next, typed as the controller declares them (see Typed state and parameters): a case of itsStateenum (ControllerState:Init,Display,InitInput,ReadInput, or its own), and an object of itsParametersclass;functionKey(): the function key the user pressed, aFunctionKey(Send,Next,Previous,Refresh,Summary,Guide,Cancel,Correction), or null for a connection code;connectionCode()theGateway\ConnectionCode(Connect,DirectConnect,Disconnect,BackgroundCall), or null for a function key;key()gives either, as aMinitel\Key(key()?->valueis the name the gateway sent:ENVOI…, orCNX,FIN…), null when there is none: after aChangePage, at the default route started again because the context's route is unknown, and for what the gateway sends that isn't a known key (e.g.DIRECT, after aCallMode::Directcall);content(): the text typed, one string per line of the input field, andcontentAsString();terminal(): where the user connects from (remoteAddr()), and how:isAdapter()(an ESP32 or Minimit adapter, whose function keys need Shift) andisTelnetOrPhone().
Each response is built from its own class, in
Controller\Response\:Response Effect State kept by default new DisplayPage($vdt)sends Videotex content to the gateway; the next key comes back to this controller ControllerState::ReadInputRunCommand::readInput($vdt, $command)sends content and the command reading the page's input field ( Page::inputCommand(), anInputCommand: the page'sMinitel\InputField, where it is, its size and the keys validating it, and its prefill) to the gatewayControllerState::ReadInputnew ChangePage($route, $parameters)switches to another controller, which runs at once: at its initial state ( Controller::initialState()), with$parameters(aParametersobject, or none), without the user's input; this controller is resetnone: this controller is reset (its initial state, the defaults of its parameters) RunCommand::connectTo($url, $vdt)sends the user to another service, as a new connection (a ServiceCallCommandwithCallMode::Connect)none ( null): its initial stateEvery response but
ChangePageresponds to the gateway and ends the request. Their state and parameters are what this controller keeps for its next run (forconnectTo(), when the user comes back to it): aState(a case of the controller's own enum, if it has one), and aParametersobject (none by default). Give others after the content and the command (fornew DisplayPage(),readInput()andconnectTo(), by name to give only one), e.g.RunCommand::readInput($vdt, $command, parameters: new DirectoryParameters(2)).new RunCommand($vdt, $command, $state)sends any otherCommand, keeping the state given, which it requires (null: the initial state).Responsedoesn't know these classes: a response of your own (see below) is built the same way. They are readonly, and don't change the context.Servicecalls the response'scontinueWith(Flow $flow): GatewayResponse, where it says what comes next:$flow->keep($state, $parameters)keeps them for this controller,$flow->respond($vdt, $command)ends the request with that response to the gateway, and$flow->goTo($route, $parameters)resets this controller and runs another one, giving its gateway response. Every response butChangePageextendsKeepingResponse, which keeps the state and parameters it is built with, then calls itsnext(Flow $flow). A response of your own does the same, without a change toService:final readonly class ClearAndShow extends KeepingResponse { public function __construct(private Vdt $vdt) { parent::__construct(ControllerState::ReadInput, null); } protected function next(Flow $flow): GatewayResponse { return $flow->respond(Vdt::clearScreen()->append($this->vdt)); } }
-
AbstractControllerruns the method of the request's state, so a controller only writes what each state does:/** @extends AbstractController<NoParameters> */ final class HomeController extends AbstractController { public const NAME = 'home'; public function __construct(private Page $page) {} // What it keeps besides its state: nothing public function parametersType(): ParametersType { return ParametersType::none(); } // Shows the screen (onInit() and onInitInput() do the same, unless overridden) protected function onDisplay(Request $request): Response { return RunCommand::readInput($this->page->display($request->terminal()), $this->page->inputCommand()); } // Handles the key pressed and what was typed protected function onReadInput(Request $request): Response { if ($request->functionKey() === FunctionKey::Guide) { return new ChangePage('help'); } return RunCommand::readInput(Vdt::line0('Unknown code'), $this->page->inputCommand()); } }
A state it doesn't know (e.g. kept by an older version of the service) starts it again. A controller with states of its own implements
Controllerwith its ownStateenum. -
PaginatedControllershows the items of aPaginatedListone page at a time: Suite and Retour change page, with "Première page" / "Dernière page" on line 0 at the ends (FrameworkMessage::FirstPage,LastPage: see Messages), Répétition redraws the page, and the page index is kept inPageParameters. The list gives the number of items and of items per page, the data of a page from itsPaginator, and handles the other keys on theShownPage, with$page->display(),$page->stay($vdt)(reads the next input on the page, after$vdt),$page->next()/previous()(the next or previous page, or the end message) and$page->message()(a message of the page):final readonly class DirectoryList implements PaginatedList { public function __construct(private Directory $directory) {} public function itemCount(): int { return $this->directory->count(); } public function itemsPerPage(): int { return 4; } // The template also gets the paginator's variables: {{page}}, {{pageCount}}, {{itemCount}}... public function pageData(Paginator $paginator): array { return ['services' => $this->directory->getServices($paginator->offset(), $paginator->limit())]; } public function onOtherKey(Request $request, ShownPage $page): Response { return match ($request->functionKey()) { FunctionKey::Summary => new ChangePage('home'), FunctionKey::Send => $page->next(), default => $page->stay(), }; } } // The route's controller new PaginatedController($page, new DirectoryList($directory));
-
Paginator(new Paginator($itemCount, $perPage, $index)) is a page ofitemCount()items,limit()at a time (immutable; there is always one page, empty without items, and an index out of the pages is kept within them):Method Gives offset(),limit()what to retrieve for the page (e.g. LIMIT/OFFSETof a query)slice($items)the page's items, out of a list of all of them index(),number()the page, from 0 (what PageParameterskeeps) and from 1 (what the user sees)itemCount(),pageCount(),itemCountOnPage()the number of items, of pages, and of items on this one firstItem(),lastItem()the numbers of its first and last items, from 1 (0 without items) isFirst(),isLast(),next(),previous(),at($index)where it is, and the pages around it ( next()andprevious(): null at the ends)toArray()the variables of a template: page,pageCount,itemCount,perPage,firstItem,lastItem -
Typed state and parameters. What a controller keeps is typed from end to end, and the static analysis checks it. A controller declares:
initialState(): a case of the string-backed enum of its states, implementingState(ControllerState::Initfor anAbstractController);parametersType(): the type of its parameters, aParametersTypeof a class implementingParameters(ParametersType::of(DirectoryParameters::class), orParametersType::none()for none). The class is immutable (readonly): the context keeps the object the controller is given, so changing it would change what the route keeps;
and gets them typed:
Request<TState, TParameters>,$request->state()and$request->parameters(). Its responses keep a case of its enum and an object of its class (null: the initial state, the default parameters); another type is an error. The statenew DisplayPage($vdt)andRunCommand::readInput()keep by default isControllerState::ReadInput: a controller with its own enum gives them one of its states, asSearchControllerdoes below.Static analysis checks it (Mago, which the framework is checked with): a response is typed by the states it keeps (
Response<ControllerState>,Response<SearchState>), andrun()returns aResponse<TState>of the controller's. A response keeping another enum's state, such as the defaultReadInputinSearchController, is reported there, instead of failing at run time. A method returning a response for the controller says which, e.g.@return Response<SearchState>(anAbstractController'sonDisplay()andonReadInput()already returnResponse<ControllerState>).ChangePagekeeps no state (Response<never>): any controller can return it. To keep the initial state withnew DisplayPage(), give it (SearchState::Init) rather thannull, which the analyzer types as the default.final readonly class DirectoryParameters implements Parameters { public function __construct(public int $page = 0) {} // From what the context kept: a missing or invalid value gets its default public static function fromValues(Values $values): static { return new self(max(0, $values->int('page'))); } public function toArray(): array { return ['page' => $this->page]; } } enum SearchState: string implements State { case Init = 'init'; case ReadQuery = 'read-query'; } /** @implements Controller<SearchState, DirectoryParameters> */ final class SearchController implements Controller { public function initialState(): SearchState { return SearchState::Init; } public function parametersType(): ParametersType { return ParametersType::of(DirectoryParameters::class); } public function run(Request $request): Response { $page = $request->parameters()->page; // DirectoryParameters if ($request->state() === SearchState::ReadQuery) { // ... } return RunCommand::readInput($vdt, $command, SearchState::ReadQuery, new DirectoryParameters($page + 1)); } }
Valuesreads what the context kept (JSON, from a previous request, possibly of another version of the service, or forged):int($name, $default),string(),bool()andarray()coerce what is safe ('12'or12.0to12,'+007'to7, a number to text,1/0and'true'/'false'to a bool), and give the default for anything else.Behind it,
RouterBuilder::addRoute()binds each controller with its types (Route), in the immutableRouterit builds, and theContextkeeps aRouteContextper route.Core\ContextSerializerwrites it as JSON (the enum's value andtoArray()), and restores it with these types (a state the enum doesn't have is the initial one, routes kept that the router doesn't have are dropped, and a context whose current route it doesn't have is refused with anUnknownRouteException).initialState()andparametersType()are called for routes that don't run: they must not use the controller's properties, so that lazy controllers stay unbuilt. -
Gateway\ConnectionCodenames the connection codes ofRequest::key()(CNX,DIRECTCNX,FIN, and the start of background calls,BGCALL-WM-):ConnectionCode::of($key),Request::connectionCode(), orGatewayRequest::$key.
Testing a service
Testing\ServiceTester scripts a session of a user against a Service, without the gateway,
in a PHPUnit test (PHPUnit is suggested by the framework, not required: add it to the
service's require-dev; without it, ServiceTester's constructor says so). It runs the
service on requests built in memory, gives the context of each response back with the next
request, and plays every response since the connection on a simulated Screen, as the Minitel
keeps what isn't cleared:
$serializer = new ContextSerializer($router); $tester = new ServiceTester(new Service($router, $messages, $serializer), $serializer); // optionally, a Terminal $tester->connect()->assertRoute('home')->assertScreenContains('BIENVENUE') ->type('2')->press(FunctionKey::Send)->assertRoute('games') ->press(FunctionKey::Summary)->assertRoute('home');
connect()starts a new session (an empty screen, no context),type(...$lines)gives the text of the input field for the next key (one string per line),press(FunctionKey)sends a key, anddisconnect()checks a disconnection gets no response.assertScreenContains(),assertScreenNotContains(),assertLineContains($row, ...)andassertLine0()check the screen as text, accented characters included (Screen::text());assertRoute()the route the user's next key goes to, andassertConnectsTo($url)a connection to another service (RunCommand::connectTo()). A failed assertion shows the screen.screen(),response()(the lastGatewayResponse) andcontext()give the rest, for other assertions.
To test the service as it is served, build its Service from the same wiring as its
public/index.php: the skeleton keeps it in config/container.php, which
its public/index.php and its tests/ both require.
Messages
Text shown on the Minitel is not written in the code: it is read from messages files, by name.
- Names are enum cases implementing
Message\Message, whose value is the name in the files:FrameworkMessagefor the framework's (error,page.first,page.last,endkey,endkey.shift, and for the HTML view the key labelskey.*andweb.leave), and an enum of its own for a service's. - Texts come from
config/messages.xmlin the framework (its defaults,MessagesXmlParser::defaults(), read where the service is built), then the service's messages file over them, then a page's<message>over those, for that page. A text can have{{placeholders}}, as in page templates:{{name}}, or a dotted path through arrays and public object properties ({{user.name}}). - Always given:
Service,PageXmlParserand the pages take the messages as a required argument, never a hidden default: pass(new MessagesXmlParser())->defaults()for the framework's only.
<messages xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../vendor/remi-san/minipavi-service/schema/messages.xsd"> <message name="service.unknown">Service inexistant</message> <message name="connected.from">Connexion de {{remoteAddr}}</message> <message name="page.last">Fin de la liste</message> <!-- redefines the framework's --> </messages>
enum AccMessage: string implements Message { case UnknownService = 'service.unknown'; case ConnectedFrom = 'connected.from'; } // Composition root: read and checked at startup (every message of these enums has a text) $parser = new MessagesXmlParser(); $messages = $parser ->parseFile("$config/messages.xml", $parser->defaults()) ->check(FrameworkMessage::class, AccMessage::class); $parser = new PageXmlParser($messages); // pages redefine them with <message> $service = new Service($router, $messages, new ContextSerializer($router), logger: $logger); // for its error message // In a controller: the page's text, its placeholders replaced Vdt::line0($this->page->message(AccMessage::ConnectedFrom, ['remoteAddr' => $addr]));
A message without text, a placeholder without its variable or whose value isn't text (an
array, an object without __toString()), or a {{...}} that isn't a placeholder ({{1}},
{{user-name}}: a page template would leave it as it is) is a LogicException naming the
message; a messages file that can't be read is a MessagesException with the file and line.
schema/messages.xsd describes messages files.
Reading files
PageXmlParser (pages and their .vdt files, through PageFiles), MessagesXmlParser
(messages files, the framework's included) and HtmlRenderer (the font of the HTML client)
read files through an Io\FileReader: read($file) gives the content, or null if it can't
be read. By default it is Io\Files, which reads them from disk. Give another as their last
argument to read them from elsewhere, e.g. from memory in a test:
// $files implements FileReader $messages = (new MessagesXmlParser($files))->parseFile('messages.xml', (new MessagesXmlParser())->defaults()); $parser = new PageXmlParser($messages, files: $files);
MessagesXmlParser::defaults() reads the framework's messages (config/messages.xml, in the
framework's folder) through its reader too. With a reader that doesn't have them (e.g. one
from memory), read them with a MessagesXmlParser built without a reader, as above, or have
the reader fall back to Io\Files.
Page XML format
A page file has a <page> root, read by PageXmlParser. Errors throw a PageXmlException
giving the file and line. They are found when the page is parsed (minipavi lint parses every
page, see Command line): the elements of a static page, and those of a
template without placeholders, are built then (a missing .vdt file, an unknown color...).
Only a template's elements with placeholders are built when displayed, and their errors throw
a TemplateException, with the file and line too; in a <foreach>, so is an element's row. The screen is 40 columns × 24 rows (row 0 is the status line), and
elements are drawn in order:
| Element | Draws |
|---|---|
<background>file.vdt</background> |
Videotex page from the page's folder or one of its subfolders (e.g. images/logo.vdt; / or \ between folders, but not first, nor .. or a Windows drive such as C:), sent as is (e.g. made with a Videotex editor). Put it first to draw over it. |
<image row col>file.vdt</image> |
Videotex picture from the page's folder or one of its subfolders, drawn with its top-left cell (row 1, column 1 of the file) at row, col (default 1, 1): what goes past the screen is cut, and it doesn't clear the screen. In a template, the file name can be a placeholder ({{game.image}}), and in a <foreach>, row is relative to the item, to show a picture per item |
<text row col align="center" color bg size fill="yes">…</text> |
text; size: normal, double-height, double-width, double; fill="yes" paints the rest of the row with bg |
<line row col length char color/> |
horizontal line; char: top (_), middle (`), bottom (~) or any character |
<key row col color bg>Envoi</key> |
function key badge, in reverse video (bg: around it) |
<endkey row color/> |
"Connexion/fin" hint, centered, with "[Maj] +" for ESP32/Minimit adapters (messages endkey, endkey.shift) |
<input row col length lines validwith/> |
input field read by Page::inputCommand() (default: row 13, 2 lines, to the end of the row) |
validwith: keys validating the input, separated by spaces (defaultenvoi): envoi, sommaire, annulation, retour, repetition, guide, correction, suite (FunctionKey::xmlName()). A one-line field is a text input where every key validates; with several lines, Suite and Retour move between them.- Colors: black, red, green, yellow, blue, magenta, cyan, white.
coldefaults to 1.
<page> can also set up the Minitel, sent by Page::display() before the content (a setting
left out is left as it is):
| Attribute | Values | Sets |
|---|---|---|
keyboard |
uppercase, lowercase |
the case of the letters typed (the Minitel starts in uppercase) |
echo |
on, off |
whether the Minitel shows what is typed itself: off when the gateway's input commands show it |
scroll |
on, off |
whether the screen scrolls up past the last row: off for page mode |
e.g. <page type="static" keyboard="lowercase" echo="off" scroll="off">, for a screen
reading what the user types.
At its top level, <message name="page.last">Fin de l'article</message> redefines a message
of the service for this page (see Messages).
<page type="static"> is drawn as is. <page type="template"> can also have placeholders and
instructions, filled in with the data given to Page::display($terminal, $data):
| Syntax | Meaning |
|---|---|
{{name}}, {{service.code}} |
placeholder, in any text or attribute (not in <input>); dotted paths go through arrays and public object properties (or those an object gives through __isset() and __get()): any other is an unknown variable |
<foreach items="services" as="service" row="5" step="2">…</foreach> |
repeats its content for each item, step rows apart. Inside, rows are relative to the item (0 = its first row), and loop.index (from 1), loop.count, loop.first and loop.last are available |
<if test="loop.last">…</if> |
content shown only if the variable is set and not empty |
<if test="!loop.last">…</if> |
… or only if it is not |
Elements of a service
A service adds its own display elements by giving PageXmlParser a Page\Parser\PageElements
after its messages. For each page, builders() gets the files of the page's folder
(PageFiles) and the page's messages, and returns an ElementBuilder per element: its tag,
how it is built from its attributes and text (placeholders already replaced), whether its
row is relative inside a <foreach>, and whether it can be in one.
final readonly class GameElements implements PageElements { public function builders(PageFiles $files, Messages $messages): array { return [new ScoreBuilder()]; // <score row="3" value="{{game.score}}"/> } } $parser = new PageXmlParser($messages, new GameElements()); // With PHP-DI: PageXmlParser::class => create()->constructor(get(Messages::class), get(GameElements::class))
The parser takes one PageElements: a service with several sets of elements returns all their
builders from one.
A builder reports what is wrong in the page with a PageXmlException or an
InvalidValueException, as Position, Span, InputField and PageFiles::read() do: the
parser gives it the file and line, as for the framework's elements. Any other exception is a
bug of the builder, and goes through as it is, as does an exception of a variable's own code
(its __get(), __toString()...) read by a template or a message.
A tag of the format (text, foreach, input...) can't be taken again, nor one tag by two
elements: building the PageXmlParser then throws a LogicException, at boot. For this check,
builders() is also called once with a placeholder folder: building the builders must not
read the files. The keys of the array it returns are ignored. These elements aren't in the XML
Schema, which rejects them, and minipavi lint and minipavi preview only know the
framework's.
XML Schema
schema/page.xsd describes the format as an XML Schema (1.0), for editors to complete and
check pages as they are written. A page points to it with xsi:noNamespaceSchemaLocation,
relative to the page, e.g. from a service's config/pages/:
<page type="template" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../vendor/remi-san/minipavi-service/schema/page.xsd">
xmllint --noout --schema vendor/remi-san/minipavi-service/schema/page.xsd config/pages/*.xml
checks pages from the command line. The parser remains the reference: the schema can't
express some of its rules, listed at the top of page.xsd (e.g. <foreach> or a
placeholder in a static page, or a second <input>), and refuses unknown attributes, which
the parser ignores. tests/Page/Parser/PageXsdTest.php keeps the two in agreement: when the
format changes, change page.xsd with the parser.
Videotex content
Videotex goes through the framework as a Vdt value, never as a string: pages display
one (Page::display()), responses and Flow::respond() take one, and GatewayResponse holds
one. Only the gateway client (MiniPaviClient::send()) turns it into bytes. Text and
Videotex can't be mixed up:
Vdt::text('Déjà vu'); // text: its accents encoded in G2 new Vdt("\x0C"); // raw Videotex Vdt::line0('Choix inconnu'); // on the status line (MiniPaviCli's writeLine0()) $page->display($terminal)->append(Vdt::line0('Bienvenue')); // one after the other Vdt::join($a, $b, $c);
A Vdt keeps its bytes, and reads them only to play, show or move them (below).
Codes to send as they are have names: Vdt\Videotex for Videotex (CLEAR_LINE,
CURSOR_OFF, INVERSE_ON, sizes, RESET_CHARSETS..., and the colors of a
Minitel\Color: Videotex::textColor($color) and backgroundColor($color)), and the Minitel\Keyboard,
Minitel\LocalEcho and Minitel\Scroll enums for the sequences configuring the Minitel
(Keyboard::Lowercase->sequence()...). A page sends them itself, from the attributes of
<page> (see Page XML format); Page\Setup sends them for other content.
They replace MiniPaviCli's global VDT_* and PRO_* constants, which are only defined once
MiniPaviCli is loaded. Vdt holds Videotex content, its bytes, and joins it (join(),
append()). Its constructors encode as MiniPaviCli's Videotex helpers do, without calling
them: Vdt::text() (as toG2()), Vdt::position($position) (a Minitel\Position,
setPos()), Vdt::line0() (writeLine0()), Vdt::clearScreen() and
Vdt::repeat($char, $count) (repeatChar(), up to 64; beyond, as one REP can't count more,
more follow, as the MiniPavi emulator writes them; a count below 1 is an
InvalidValueException).
Other classes read Videotex content, e.g. of a .vdt file: Screen::of() draws it, Offset
moves it on the screen, and ClearScreens works on its clear screens; <image> uses them.
use MiniPaviService\Vdt\Offset; use MiniPaviService\Vdt\Screen\Screen; use MiniPaviService\Vdt\Vdt; $picture = new Vdt(file_get_contents('picture.vdt')); $moved = (new Offset(8, -2))->apply($picture); // 8 columns right, 2 rows up (negative: left, up) echo $moved->toString(); // the Videotex content echo Screen::of($moved)->preview(); // the screen, as text
(new Offset($x, $y))->apply($vdt): Videotex positions are mostly absolute, but text also flows from cell to cell and wraps at column 40, so the content is played on a simulated screen (Vdt\Player) rather than having its positions patched. Characters that end up off the screen are dropped instead of wrapping onto the next row, and the cursor is positioned again where needed, with the current attributes (character set, colors, size...), which a positioning resets. Row 0, the status line, is not moved. A double-height or double-size character moved onto row 1, where the Minitel discardsESC MandESC O, is written without them: at normal size, or double width for double size, in the columns it had. Text keeps its zone (seeScreen::of()): each delimiter is written withESC ZorESC Ybefore it, and a space that would otherwise start another zone (a background colour sent again waits for it) or lose its own (its delimiter went off the screen) is written as a delimiter of its zone. That space isn't underlined, as a delimiter isn't. Text moved to column 1 before such a space has no column left for its delimiter, and loses its zone.ClearScreens:removed($vdt)is the same content without its clear screens (FF), to draw it over other content, andfromLast($vdt)the content from its last one, what still shows.HtmlRenderer::render($screen, $overlay): the screen in HTML (a<div class="minitel">, with$overlayover it),style()its CSS (the cell size in--w,--h, the Minitel font in--font) with the font embedded, andplace($position, $length)the style placing an element over a cell, with all of its geometry (position, size, its border included, and stacking above double-height cells), so the element's own style only says how it looks (it is inline, so it takes over the element's ownposition,height,box-sizingandz-index); the page around it is the HTML client's (Client\HtmlForm, seeHtmlClientabove).Screen::of($vdt): theScreendrawn by the content: aCell(character and attributes) ornullper row and column.line($row)andtext()give the text of a row and of the screen, G2 characters decoded (é,£,½,Œ...;Cell::text()), andpreview()the same rows framed and numbered, to read in a terminal. As on a Minitel,ESC M(double height) andESC O(double size) received on rows 0 and 1 are discarded, the size staying as it was; a double height already set when a cursor move (LF, VT) brings the cursor onto row 1 is kept, the character drawn over row 0. A tall text character (double height or double size) wrapping at the end of a row goes 2 rows down, cycling through rows 1 to 24 (24 to 2, 23 to 1), and the text carries on along that row; a move right (HT) from column 40 goes 1 row down, as BS, LF and VT move 1 row. SO and SI set the size back to normal and turn off inverse video and separated mosaic, SO also underline; a size (ESC LtoESC O) or inverse video (ESC ]) received in mosaic is discarded: mosaic characters are never tall, wide or inverse. Underline in text is a zone attribute:ESC ZandESC Ywait for a delimiter, a space drawn while a zone attribute (underline, background colour, masking) waits. The delimiter isn't underlined, and starts a zone running along its row up to the next delimiter, mosaic or empty cell, over what is already there too: writeESC Z, a space, then the text (asPage\Display\Keydoes). A positioning drops what waits, and SO ends the zone. CAN clears with spaces, so while a zone attribute waits, the first one is a delimiter. A mosaic character uses up nothing that waits. Background colour and masking are still applied at once.Vdt\Player::play($vdt, $listener)(internal, whatScreen::of()andOffsetare built on): plays the content on the simulated screen, telling aVdt\ScreenListenereach character (glyph(), with its row, column, width and attributes), each delimiter (delimiter(), with theScreen\Zoneit starts), each CAN (clearLine(), with the zone its first space starts if it is a delimiter) and the otherTokens (sequence()).Screen\ScreenCells::of()collects the cells ofScreen::of(),Vdt\OffsetWriter::write()writes the content moved byOffset: each listens to one content, built by that static method only.
bin/minipavi vdt-offset does the same from the command line (see Command line).
Command line
bin/minipavi is the framework's command line, built with symfony/console: Composer installs
it in a service as vendor/bin/minipavi (minipavi list lists its commands, minipavi help <command> describes one). The commands reading pages take
the service's messages with --messages, as the service reads them (a page's <message>
must be one of them); without it, the framework's only.
vendor/bin/minipavi lint --messages config/messages.xml config # every page, for CI vendor/bin/minipavi preview config/pages/games.xml games.json # the screen of a page vendor/bin/minipavi vdt-offset --preview -- images/background.vdt 8 -2 # move a Videotex page
lint [--messages <messages.xml>] <path>...parses every page (XML file whose root is<page>) of the files and folders given, with their subfolders, as the service does: other XML files are skipped. Each error is printed with its file and line, and the command exits with 1 on an error, or if it found no page. The skeleton runs it withcomposer lint, in CI.preview [--messages <messages.xml>] <page.xml> [<data.json>]prints the screen a page draws, as text (Screen::preview()): a template with the variables of a JSON object (e.g.{"games": [{"name": "Rocket Rescue"}]}).vdt-offset [--preview] <input.vdt> <x> <y> [<output.vdt>]moves the content of a Videotex page byxcolumns andyrows (negative: left, up), withOffset(see Videotex content): to the output file, or the standard output; input-reads the standard input.--previewprints the screen as text, before and after. A negative number would be read as an option: put--before the arguments (vdt-offset -- background.vdt 8 -2).
Exit codes: 0 on success, 1 when the command fails (an error in a page, a file it can't read
or write, a wrong command line). The commands are Symfony Commands, in Cli\.
Developing the framework
The code is checked with Mago (mago.toml): its formatter
(PER Coding Style, 120 columns, one import per use), its linter and static analyzer,
which fail on any issue, notes included, and its guard, which checks the layers'
dependencies: a namespace uses only the layers and libraries its rule permits. mago.toml
says why each rule turned off or ignored is, the ignored ones only in the files where they
occur. There is no baseline of known issues: a rule is turned on with its issues fixed. (A
baseline brought back would need --fail-on-out-of-sync-baseline in composer analyse again,
so that its stale entries fail.)
stubs/MiniPaviCli.php gives the types MiniPaviCli doesn't declare (a patch of the library's
class). Every file has declare(strict_types=1).
composer install # once, in this folder: development tools in vendor/ composer cs # checks the formatting composer cs-fix # formats the code composer analyse # linter, static analysis and layers (mago lint, mago analyze, mago guard) composer test # tests (PHPUnit, tests/) composer coverage # tests with coverage, as text and in coverage.xml (needs pcov or Xdebug) composer mutation # mutation testing (Infection, needs pcov or Xdebug), logs in build/infection/
composer coverage fails when the tests cover less than 97.5% of the lines of src/
(tools/coverage-minimum.php reads it from coverage.xml). The minimum is raised as the
missing tests are added, never lowered to let a change through.
Coverage says which code the tests run, not whether they would notice it being wrong:
composer mutation (Infection, infection.json5) changes
the code of src/ in small ways (mutants), and runs the tests that cover each one. A mutant
the tests don't notice (escaped, listed in build/infection/infection.log) is a test missing,
or code nothing needs. It gives the Mutation Score Indicator (MSI, the share of mutants
noticed) and the covered MSI (among the mutants of covered code), and fails when either is
below its minimum in infection.json5 (90%), raised as mutants are killed. It runs the
tests without UPDATE_GOLDEN, so it never writes the golden files.
Tests are in tests/, with their files in tests/fixtures/. Pages are checked through the
screen they draw (Screen::preview()). Offset is checked in two ways: against the
property that the moved screen is the original one moved, and byte for byte against golden
files (tests/fixtures/vdt/*.offset_*.vdt). Run UPDATE_GOLDEN=1 composer test to rewrite
the golden files after an intended change.
A new display element of the framework is a Page\Parser\Element\ElementBuilder (see
Elements of a service), added to StandardElements; then the XML
Schema (schema/page.xsd) and the Page XML format above.
The other tags (<input>, <foreach>, <if>, <message>) each have their
Page\Parser\Tag\TagParser, by tag in NodesParser::standard(), which reads the children
of an element with them, and gives the nodes and the page's <input> (ParsedNodes).
GitHub Actions runs the three checks on PHP 8.2, 8.3, 8.4 and 8.5 for every change to the framework, and the coverage (with its minimum) and the mutation testing (its MSI in the job's summary, with its minimum) on PHP 8.4.