PHPackages                             eukras/koinos - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. eukras/koinos

ActiveLibrary[Utility & Helpers](/categories/utility)

eukras/koinos
=============

Work with Biblical references and Unicode Greek text

v1.1.2(12y ago)1341MITPHPPHP >=5.4.0

Since Jan 16Pushed 7y ago2 watchersCompare

[ Source](https://github.com/eukras/koinos)[ Packagist](https://packagist.org/packages/eukras/koinos)[ Docs](http://github.com/eukras/koinos)[ RSS](/packages/eukras-koinos/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)DependenciesVersions (6)Used By (0)

[![Koinos logo](src/Resources/public/images/koinos-logo-400w.jpg)](src/Resources/public/images/koinos-logo-400w.jpg)

koinos
======

[](#koinos)

A PHP library and composer package for working with:

- Biblical references in texts and databases, and
- Classical and Koine Greek text in Unicode.

Κοινός means 'common' in Ancient Greek. This package contains a number of reusable services and utilities from the [Hexapla](http://hexap.la) project.

Installation
------------

[](#installation)

You will need PHP >=5.4 and phpunit >=4.0.

In `composer.json`:

```
"require": {
    "eukras/koinos": "~1.1"
}
```

Tests
-----

[](#tests)

The tests are the best documentation for developers.

```
composer dump-autoload   # updates /vendor for autoloading; see .gitignore
phpunit -c tests
```

Library data files
------------------

[](#library-data-files)

```
./src/Resources/library/lxx/books.csv
./src/Resources/library/nt/books.csv
```

In each file the CSV lines specify id, library-name, name, short-name, handle, reference-depth, aliases, total-chapters.

- Handles are the short names used in URIs, e.g. `Romans 1` has handle `rom+1`.
- Normal books like 1 Corinthians are reference depth 2 (chapter:verse), but single-chapter books like Philemon are identified by verse only, so have a reference depth of 1.

```
...
107,NT,1 Corinthians,1 Cor,1cor,2,1co,16
...
118,NT,Philemon,Phm,phm,1,phl/philem,1
...
```

Service\\ReferenceManager and Utility\\Reference
------------------------------------------------

[](#servicereferencemanager-and-utilityreference)

The ReferenceManager is use to construct, manipulate and format References.

```
./src/Utility/Reference.php
./src/Service/ReferenceManager.php
./tests/Utility/Reference.php
./tests/Service/ReferenceManager.php
```

### Examples

[](#examples)

Initialise the ReferenceManager as follows:

```
use Koinos\Service\ReferenceManager;
$rm = new ReferenceManager($libraries=['nt', 'lxx']);
```

Libraries are easy to create: just add `Resources/library/$library/books.csv`(see above), and pass `$library` as a constructor argument.

The ReferenceManager handles most Reference operations.

```
$mattId = $rm->matchBookName('matt');  //  returns (int)101, say.
$matt28 = $rm->createReferenceFromBookAndChapter($mattId, 28);
```

`$matt28` is now a `Reference` object.

```
$mark1 = $rm->getNextChapterReference($matt28);

echo $rm->getShortTitle($matt28);  //  Matt 28
echo $rm->getHandle($matt28);      //  matt+28
```

You will normally want to work with complex human-readable reference strings:

```
$ref1 = $rm->createReferenceFromQuery('1 Cor 16:1-5,8,10-12,13-14');
$ref2 = $rm->createReferenceFromQuery('1cor+16.1-4,5,8,10-14');
```

In this example `$ref1` generates identically to `$ref2`. Adjacent verse ranges are combined together into a standard reference. Koinos does not know or care how many verses are in a given chapter, though; internally, full-chapter links are treated as Book 1:1-999.

```
echo $rm->getTitle($ref1);  //  1 Corinthians 16:1-5,8,10-14
echo $rm->getTitle($ref2);  //  1 Corinthians 16:1-5,8,10-14

$ref1->equals($ref2);       //  true
$ref1->contains($ref2);     //  true
```

All this together allows HTML links to be generated easily, though in a framework you would most likely plug `$rm->getHandle($ref)` into a route.

```
echo $rm->getLink($matt28, $uriPrefix='/r/');
```

Being able to generate links allows them to be auto-replaced in text:

```
$linkedHtml = $rm->linkReferencesInHtml($textContainingReferences, '/r/');
```

The scanner for matching links in text will identify if they exist in parallels, that is, if references are separated by a pipe character, e.g. "The Psalms Ps 14 | Ps 53 are the same." See the test suite for examples.

### Utility\\Reference Internals

[](#utilityreference-internals)

Internal working is done with quadruples of `[book, section, chapter, verse]`; In `$ref1`, 1cor is book #107, and has two-level referencing (c:v), so the section number is always 1. Every quadruple becomes an `UNSIGNED INT(12)` for SQL (see below).

QueryQuadrupleIndex1 Cor 16:1\[107, 1, 16, 1\]107001016001This makes it easy to efficiently index and match references and ranges:

```
echo $ref1->getSqlClause($columnName='reference');

//  (reference BETWEEN 107001016001 AND 107001016005) OR
//  (reference BETWEEN 107001016008 AND 107001016008) OR
//  (reference BETWEEN 107001016010 AND 107001016014)

echo $ref1->getSqlRangeClause($startColumn='rangeBegins', $endColumn='rangeEnds');

//  (rangeEnds >= 107001016001 AND rangeBegins = 107001016008 AND rangeBegins = 107001016010 AND rangeBegins