README

ArabicRomanNumberConverter is a composer package, which converts an arabic or roman numeral to the opposite numeral.

Getting started
1. Requirements
2. Installation
Usage
1. Basic
2. Further
Docker
Authors

Getting Started

Requirements

Your local machine must run with at least PHP 8.0
Be sure to have composer installed

Installation

Use composer to download and install ArabicRomanNumberConverter.

You can add ArabicRomanNumberConverter as a local, per-project dependency to your project:

$ composer require oliver-noth/arabic-roman-number-converter

If you only need ArabicRomanNumberConverter during development, then you should add it as a development-time dependency:

$ composer require --dev oliver-noth/arabic-roman-number-converter

Usage

Basic

First instantiate a new number converter

$factory = new \OliverNoth\ArabicRomanNumberConverter\Main\Factory();

/**
 * Numeral can be passed in different ways:
 */

// 1.) Pass it to the constructor
$numberConverter = $factory->createNumberConverter('MCMLXVIII');

// 2.) Pass it to the setter method
$numberConverter = $factory->createNumberConverter()->setCandidate('MCMLXVIII');

then get the converted numeral

$converted = $numberConverter->convert(); // $converted will be (int) 1968

or get another conversion without creating a new number converter by passing in another numeral

$converted = $numberConverter->convert(1968); // $converted will be (string) 'MCMLXVIII'

You can get conversion notes (especially those from failed validation)

$notes = $numberConverter->getConversionNotes();

Further

See example/basic-usage.php to get an idea on how to use ArabicRomanNumberConverter in your project.

Docker

Set up a docker container on your local machine using ddev.

Prerequisites

Be sure to have docker installed and running. If not, follow these instructions.

Setup

Install ddev (using Homebrew/Linuxbrew is recommended):

$ brew tap drud/ddev && brew install ddev

Create and cd into your project directory (replace folder name `<PATH-TO-YOUR-PROJECT-DIRECTORY>/my-project` according to your needs):

$ mkdir -p <PATH-TO-YOUR-PROJECT-DIRECTORY>/my-project
$ cd <PATH-TO-YOUR-PROJECT-DIRECTORY>/my-project

Create a new docker container

Configure a ddev docker container (replace project-name my-project according to your needs):

$ ddev config --project-name=my-project --project-type=php --php-version=8.0 --docroot="" --create-docroot --disable-settings-management --http-port=8088 --https-port=44388

Create configured container and clone composer package into it:
IMPORTANT: Eventually arising question `Warning: ALL EXISTING CONTENT of the project root (~/my-project) will be deleted` must be answered with 'yes'

$ ddev composer create oliver-noth/arabic-roman-number-converter

Create index.php in document root of created container:

$ ddev exec chmod 755 example/write-index.sh && ddev exec ./example/write-index.sh

Finally start created container

$ ddev start

Once you have started the container, your project can be reached at `http://my-project.ddev.site:8088.<br> NOTE: Subdomainmy-project` should be replaced with project-name you have chosen before.

Unit tests

This package is completely unit tested. You can run them in the created container:

$ ddev exec vendor/bin/phpunit

Displaying a code coverage summary needs enabling a code coverage driver. Use xdebug, check it and get the summary:

$ ddev xdebug
$ ddev xdebug status
$ ddev exec vendor/bin/phpunit --coverage-text

NOTE: Although code coverage is at 100%, maybe the container displays a smaller coverage.
Running it on your local machine (assuming a code coverage driver like xdebug is installed) in your project directory should display 100%. Working on a fix...

$ vendor/bin/phpunit --coverage-text

Digging deeper

For instance managing the webserver behaviour of the container acting as such could be done by entering the container:

$ ddev ssh

MORE: Complete documentation can be found at ddev.readthedocs.io

Authors

Oliver Noth

oliver-noth / arabic-roman-number-converter

Maintainers

Details