commocore/petscii

Converts text to PETSCII compatible format (used on Commodore 8-bit computers)

v1.2.0 2019-10-04 17:52 UTC

This package is auto-updated.

Last update: 2020-01-04 18:31:20 UTC


README

Petscii is a tiny PHP library which converts text to PETSCII (PET Standard Code of Information Interchange) format, a character set based on ASCII. It has been used in Commodore Business Machines - the 8-bit home computers like VIC-20, C64, C128, CBM-II, Commodore Plus/4, C16 and C116.

With this package, you can prepare your website to be fully compatible with web browsers available for Commodore 64 or Commodore 128 connected to internet via one of existing ethernet cartridges: 64NIC+, The Final Ethernet, RR-Net or other. You can even surf the web using an emulator.

This package is used on www.commocore.com website.

Supported browsers

Petscii package has been tested on a few Commodore 64 browsers. Please let me know if you're using other ones, or you've encountered any issues. Also, please let me know if some of the links below are no longer available. Petscii also allows extending the list of supported browsers by user-defined one.

Contiki web browser

Online HTML web browser available with a web server and other tools. Set up disk configurator for version 2.5 available here. Contiki 3 is available here.

Singular browser

Online HTML web browser. About the browser here. Set up disk available here.

HyperLink

Online HTML web browser. Not tested yet, but detected by PETSCII. More info here.

FairlightML

Offline HTML viewer also known as 64'er htmlreader. Version 0.99 is available here. You can download files using WGET (available i.a. on Contiki floppy disk).

Entering World Wide Web with emulator

If you don't have physical ethernet card, you can try Vice64 emulator for Windows (with WinPcap installed). You will find details in this Commodore Server blog entry.

Features

  • All non-ASCII characters are converted to basic ASCII-96
  • Can detect if browser is running in PETSCII mode (HTTP user agent check)
  • Pound Sterling character will be converted to the responding PETSCII character CHR$(92) for Contiki browser
  • All variations of break line tag (e.g. <br />) will be converted to <br> ( FairlightML browser cannot detect other variations)

Installation

To install via Composer, just:

composer require commocore/petscii

This package uses Composer autoloader, regular boot looks this way (for more details, see Composer documentation):

require_once '../vendor/autoload.php';

And can be imported this way:

use Commocore\Petscii\Petscii;

Usage

$content = 'Commodore 64<br />The Commodore 64 is an 8-bit home computer introduced in January 1982.<br />';

$petscii = new Petscii();

echo $petscii->render($content);

A great thing about Petscii is that you don't have to check if browser supports PETSCII. HTTP user agent is recognized automatically, and if a browser doesn't support PETSCII, text content will be displayed without any changes.

To trim single characters from the beginning and the end of the string, just provide the trim mask string as the second parameter (PHP's trim() mask is used):

$content = $petscii->render($content, "\n");

To control blank lines spacing, you can also trim HTML line breaks (<br>) from the beginning and the end of the string by using:

$result = Petscii::trimHtmlLineBreaks($this->petscii->render($text));

To check if browser is supporting PETSCII:

if ($petscii->isPetsciiBrowser()) {
    // I'm PETSCII!
}

To return browser class detected by HTTP user agent:

$browserClass = $petscii->getDetectedBrowser();

Or, to get only the class name (without namespace):

$className = substr(strrchr(get_class($petscii->getDetectedBrowser()), "\\"), 1);

To add another browser, you can just define a new class by implementing the Browseable and PetsciiBrowseable interfaces. Then, just pass it to the constructor in an array, e.g.

$petscii = new Petscii(
    array(
        new CosmicBrowser()
    )
);

Testing the package

Docker (with Docker Compose) has been used for testing purposes.

Setup

  1. First, you need to build images by executing make build.
  2. Then, you can execute make all in the main directory for the first time to install PHP dependencies and run containers, or use make composer then make start.

Executing tests

You will find all available make commands in Makefile. To test the whole project just make test. For the test coverage, if make phpunit-code-coverage-html is used, results will be saved to coverage/ folder in the HTML format.

Testing available characters

To see characters available in a particular browser, you can create test page where you can generate list of all 256 characters this way:

echo $petscii->getTestPage();

Notes

Underscore character compatibility

As Contiki browser is not using underscore character (instead left arrow CHR$(95) is displayed), and there is no equivalent available for this browser, you can ignore it, or remove underscores from text beforehand. This character is fully supported e.g. in FairlightML HTML viewer and Singular browser.

What if my website is served over HTTPS?

Unfortunately, due to limitations, c64 web browsers don't support HTTPS connections. Within nginx or Apache rewrite rules, all HTTP connections are usually forced to be redirected to HTTPS anyway.

By adjusting these rules under certain conditions, we might have a quick & dirty solution to this problem. As the list of c64 web browsers is known, we can easily create a blacklist to exclude them for HTTPS rewrites.

Redirect example for Apache:

RewriteEngine On
RewriteCond %{HTTPS} !=on
RewriteCond %{HTTP_USER_AGENT} !(Contiki|Singular|Hyperlink) [NC]
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

Redirect example for nginx:

http {
  map $http_user_agent $petscii_browser {
    default 0;
    ~(Contiki|Singular|Hyperlink) 1;
  }

  server {
    if ($petscii_browser = 0) {
      rewrite ^(.*) https://$host$1 permanent;
    }
  }
}

This way, HTTPS rewrite won't happen for particular User-Agent if it contains words such as Contiki, Singular or Hyperlink. This is also the list of all supported web browsers by this Petscii package.

Also, remember that all internal a href links on the page should be relative. Use e.g. /about-us instead of the full URL.

Caution: As User-Agent can be easily spoofed, for security reasons, be sure to limit the functionality of your website when browsed in Petscii mode. See above how to use the Petscii package to detect a browser.