Skip to content

installation.md

Latest commit

 

History

History
218 lines (169 loc) · 7.76 KB

installation.md

File metadata and controls

218 lines (169 loc) · 7.76 KB
Raw

Installation and setup

Choose the delivery model

For an end-user product, distribute a complete runtime containing PHP, the native extension, Composer dependencies, and the application's policy-approved SWORD modules. The recipient should start the product without compiling a PHP extension or running dependency-manager commands. See shipping and deployment.

Developers adding the library to an existing Composer application install the native prerequisite first:

pie install 'getbible/sword:^0.1.1'
php --ri getbiblesword
composer require getbible/scripture

The released getbible/sword PIE package contains the pinned getBibleSword and CrossWire SWORD sources. PIE builds and enables the extension for the selected PHP installation. PIE, rather than Composer, owns the native-install confirmation and any administrator prompt.

Use extension package 0.1.1 or later for this one-command installation path. The already-published 0.1.0 runtime satisfies this library's ABI requirement when it is installed, but that release used a source-asset name that PIE cannot discover through the normal package command.

Why Composer does not install the extension

ext-getbiblesword is a Composer platform dependency. Platform dependencies describe the PHP runtime that is executing Composer; Composer validates them but does not download or enable extensions. The official explanation is in Composer platform dependencies.

Adding a post-install-cmd to this library would not help. Composer executes scripts from the root application only and does not execute scripts declared by a dependency. See Composer scripts.

The root application can provide friendly Composer aliases without granting a dependency permission to execute automatically:

{
    "scripts": {
        "scripture:doctor": "@php vendor/bin/getbible-scripture scripture:doctor --json",
        "scripture:setup": "@php vendor/bin/getbible-scripture scripture:setup"
    }
}

The application operator can then run:

composer scripture:doctor
composer scripture:setup

These aliases work because they belong to the root application's composer.json; scripts declared by getbible/scripture are not inherited by the consuming project.

A Composer plugin is also unsuitable for native bootstrap. Plugins require explicit approval by the root project, may be disabled, and run with the full privileges of the Composer user. They cannot safely assume a compiler, operating system package manager, administrator access, or permission to change the active PHP configuration. Composer documents that security boundary in installing untrusted packages safely.

PIE is the dedicated extension installer. Its supported installation methods and container usage are documented by the PHP Installer for Extensions.

Application-owned bootstrap

A product that is installed from source can still present one friendly setup action. Its installer should coordinate the independent tools in this order:

  1. check php --ri getbiblesword;
  2. if the extension is missing, explain the native change and ask the operator for confirmation;
  3. after confirmation, invoke pie install 'getbible/sword:^0.1.1' for the selected PHP runtime;
  4. start a new PHP process and verify php --ri getbiblesword;
  5. run composer install or composer require getbible/scripture;
  6. invoke scripture:setup and then scripture:doctor.

The new PHP process is important: an extension enabled while Composer is already running cannot be loaded into that existing process. The installer is part of the root product, so it can express the product's supported operating systems, privilege policy, module licenses, and rollback behavior. A reusable Composer dependency cannot make those decisions for every consuming application.

For desktop products, operating-system packages, containers, and managed hosting, perform these steps while building the distributable runtime. The recipient then launches the product without PIE, Composer, a compiler, or low-level commands. For a developer checkout, the three commands at the top of this page are the shortest supported path.

Interactive application setup

Once Composer has installed the library, inspect the runtime:

vendor/bin/getbible-scripture scripture:doctor

Create an application-owned configuration interactively:

vendor/bin/getbible-scripture scripture:setup

Setup asks for:

  • an explicit configuration-file path;
  • the installed SWORD module root;
  • the writable Scripture cache root;
  • the refresh interval and lock timeout;
  • installed translation identifiers;
  • automatic snapshot refresh policy; and
  • whether configured translations should be warmed immediately.

The configuration path can instead be supplied with --config or GETBIBLE_SCRIPTURE_CONFIG_PATH. There is no implicit configuration-file location. Setup validates every value, refuses a symlink target, writes through an atomic same-directory replacement, and restricts a new configuration file to mode 0600.

For a reproducible non-interactive deployment:

vendor/bin/getbible-scripture scripture:setup \
  --config=/etc/getbible/scripture.json \
  --module-path=/var/lib/getbible/sword \
  --cache-path=/var/cache/getbible/scripture \
  --refresh-interval=P1M \
  --lock-timeout=30 \
  --module=KJV \
  --auto-refresh \
  --json

vendor/bin/getbible-scripture scripture:doctor \
  --config=/etc/getbible/scripture.json \
  --json

Use --no-auto-refresh to disable query-triggered snapshot rotation and --no-warm to save valid settings without warming installed translations. Non-interactive setup fails when no explicit configuration path is available.

Setup never invokes PIE, Composer, a system package manager, privilege escalation, a subprocess, or a network request. It configures and warms modules that are already installed. Doctor is read-only.

Programmatic initialization

Applications can construct the same services directly:

<?php

declare(strict_types=1);

use GetBible\Scripture\Configuration\Configuration;
use GetBible\Scripture\DependencyInjection\ContainerFactory;
use GetBible\Scripture\Service\ScriptureInterface;

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

$configuration = Configuration::fromEnvironment([
    'module_path' => '/var/lib/getbible/sword',
    'cache_path' => '/var/cache/getbible/scripture',
    'refresh_interval' => 'P1M',
    'lock_timeout' => 30,
    'modules' => ['KJV'],
    'auto_refresh' => true,
    'provisioning_enabled' => false,
    'install_all' => false,
]);

$container = ContainerFactory::create($configuration);

/** @var ScriptureInterface $scripture */
$scripture = $container->get(ScriptureInterface::class);
$result = $scripture->initialize(['KJV']);

if (!$result->succeeded()) {
    throw new RuntimeException(
        json_encode(
            $result->toArray(),
            JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR,
        ),
    );
}

initialize() validates and warms installed modules. With the released native ABI, it does not install a missing module. Applications that inject a mutating provisioner must explicitly enable provisioning and enforce the security and licensing contract described in module provisioning.

Verification

After setup:

vendor/bin/getbible-scripture scripture:doctor --json
vendor/bin/getbible-scripture scripture:status

scripture:doctor returns non-zero when configuration parsing or native compatibility is not ready. scripture:status additionally reports durable maintenance health; a normal warmed setup also exercises module and cache access.