sutton-signwriting/core

Core utilities for Formal SignWriting (FSW/SWU): conversion, queries, and style strings.

v1.0.1 2026-02-09 19:00 UTC

Requires

• php: ^7.3 || ^8.0
• ext-mbstring: *

Requires (Dev)

• ext-dom: *
• ext-xml: *
• ext-xmlwriter: *
• phpunit/phpunit: ^9.5

MIT

• Steve Slevinski

README

A PHP 7.3+ and PHP 8.x compliant port of the Sutton SignWriting Core for Python, focused on Formal SignWriting in ASCII (FSW), SignWriting in Unicode (SWU), FSW and SWU query languages, style strings, and conversion utilities.

Core utilities for Formal SignWriting (FSW/SWU): conversion, queries, and style strings.

Install (Composer)

composer require sutton-signwriting/core

Requirements

• PHP 7.3+
• mbstring extension required for Unicode-safe operations
• For running tests locally: dom, xml, and xmlwriter extensions (or use Docker Compose)

Usage

With Composer (recommended)

<?php
require __DIR__ . '/vendor/autoload.php';

use function Sgnw\Core\Convert\fsw_to_swu;
use function Sgnw\Core\Fsw\fsw_parse_sign;

$swu = fsw_to_swu('AS10011S10019S2e704S2e748M525x535S2e748483x510S10011501x466S2e704510x500S10019476x475');
$sign = fsw_parse_sign('AS10011S10019S2e704S2e748M525x535S2e748483x510S10011501x466S2e704510x500S10019476x475');

Without Composer (direct include)

<?php
require __DIR__ . '/src/Functions/convert.php';
require __DIR__ . '/src/Functions/style.php';
require __DIR__ . '/src/Functions/fsw.php';
require __DIR__ . '/src/Functions/fswquery.php';
require __DIR__ . '/src/Functions/swu.php';
require __DIR__ . '/src/Functions/swuquery.php';

// Example: parse an FSW sign
$sign = fsw_parse_sign('AS10011S10019S2e704S2e748M525x535S2e748483x510S10011501x466S2e704510x500S10019476x475');

// Example: convert FSW to SWU
$swu = fsw_to_swu('AS10011S10019S2e704S2e748M525x535S2e748483x510S10011501x466S2e704510x500S10019476x475');

// Example: parse an SWU sign
$sign = swu_parse_sign('𝠀񀀒񀀚񋚥񋛩𝠃𝤟𝤩񋛩𝣵𝤐񀀒𝤇𝣤񋚥𝤐𝤆񀀚𝣮𝣭');

// Example: build an SWU query from a sign
$query = swu_to_query($sign, 'ASL');

Documentation

• Online docs: https://www.sutton-signwriting.io/core-php
• Local generation: composer docs (or docker compose run --rm core-php composer docs) writes output to docs/ (generated output, not committed).
• Local preview: run composer docs, then docker compose up --build docs and open http://localhost:8090
• CI publishing: on push to main, GitHub Actions generates docs/ and publishes it to GitHub Pages (see .github/workflows/docs.yml).
  • In GitHub: Settings → Pages → Build and deployment → Source = “GitHub Actions”.

Development (Docker Compose)

This repo includes a docker-compose.yml for a reproducible PHP 7.3 environment.

Path A: action flow (up + exec)

Start the services (foreground, with build):

docker compose up --build # core-php and doc server
docker compose up --build core-php # core-php without doc server

In another terminal, run actions inside the running core-php container:

docker compose exec core-php composer test # run tests
docker compose exec core-php composer docs # rebuild docs

Path B: one-off actions (run --rm)

Run a command in a fresh throwaway container (good for CI-like tasks):

docker compose run --rm core-php composer test
docker compose run --rm core-php composer docs

Notes: service vs container

• A Compose service is a named definition in docker-compose.yml (e.g. core-php, docs).
• A container is a running instance created from a service definition.
• docker compose up creates/starts the service containers and keeps them running.
• docker compose exec runs a command in an already-running service container.
• docker compose run --rm creates a new one-off container for that command and deletes it when finished.
• If you want to start everything together, use docker compose up --build (no service name).
• When running docker compose up without -d, leave it running and use another terminal for exec.

Shut everything down:

docker compose down

Structure

Public entrypoints (Composer autoload):

• src/convert.php
• src/fsw.php
• src/fswquery.php
• src/regex.php
• src/swu.php
• src/swuquery.php
• src/style.php

Optional global wrappers (not autoloaded):

• src/Functions/*.php (explicit require_once per file)

Local development (no Docker)

If you already have PHP 7.3+ available locally:

composer install
composer test
composer docs

More verbose test output

vendor/bin/phpunit --testdox

License

MIT