README

Parses an HTML-encoded string searching for Bible references and replaces them with links to Bible.com.

Features

Link to an individual verse

 BibleLinker::linkify("Psalm 119:105", "en");
 /*
  * <a href="https://www.bible.com/bible/111/PSA.119.105.NIV">Psalm 119:105</a>
  */

Link to an entire chapter

 BibleLinker::linkify("John 3", "en");
 /*
  * <a href="https://www.bible.com/bible/111/JHN.3..NIV">John 3</a>
  */

Link to a range of verses

 BibleLinker::linkify("John 3:15-17", "en");
 /*
  * <a href="https://www.bible.com/bible/111/JHN.3.15-17.NIV">John 3:15-17</a>
  */

Link to multiple verses

 BibleLinker::linkify("John 3:16, 18", "en");
 /*
  * <a href="https://www.bible.com/bible/111/JHN.3.16.NIV">John 3:16</a>,
  * <a href="https://www.bible.com/bible/111/JHN.3.18.NIV">18</a>
  */

Specify a translation

 BibleLinker::linkify("John 3:16 (ESV)", "en");
 /*
  * <a href="https://www.bible.com/bible/59/JHN.3.16.ESV">John 3:16</a> (ESV)
  */

Abbreviate the book name with common abbreviations

 BibleLinker::linkify("Genesis 1:1", "en");
 BibleLinker::linkify("Gen 1:1", "en");
 BibleLinker::linkify("Ge 1:1", "en");
 BibleLinker::linkify("Gn 1:1", "en");
 /*
  * <a href="https://www.bible.com/bible/111/GEN.1.1.NIV">Genesis 1:1</a>
  * <a href="https://www.bible.com/bible/111/GEN.1.1.NIV">Gen 1:1</a>
  * <a href="https://www.bible.com/bible/111/GEN.1.1.NIV">Ge 1:1</a>
  * <a href="https://www.bible.com/bible/111/GEN.1.1.NIV">Gn 1:1</a>
  */

And combinations of all the above

 BibleLinker::linkify("Ge 1:1,2-3; 4; 5:6,7,8; 9:10 (NLT)", "en");
 /*
  * <a href="https://www.bible.com/bible/116/GEN.1.1.NLT">Ge 1:1</a>,
  * <a href="https://www.bible.com/bible/116/GEN.1.2-3.NLT">2-3</a>;
  * <a href="https://www.bible.com/bible/116/GEN.4..NLT">4</a>;
  * <a href="https://www.bible.com/bible/116/GEN.5.6.NLT">5:6</a>,
  * <a href="https://www.bible.com/bible/116/GEN.5.7.NLT">7</a>,
  * <a href="https://www.bible.com/bible/116/GEN.5.8.NLT">8</a>;
  * <a href="https://www.bible.com/bible/116/GEN.9.10.NLT">9:10</a> (NLT)
  */

Single chapter books don't require chapter

 BibleLinker::linkify("3 John 4", "en");
 BibleLinker::linkify("3 John 1:4", "en");
 /*
  * <a href="https://www.bible.com/bible/111/3JN.1.4.NIV">3 John 4</a>
  * <a href="https://www.bible.com/bible/111/3JN.1.4.NIV">3 John 1:4</a>
  */

Non-existant chapters and verse do not get linked

 BibleLinker::linkify("Psalm 150; 151", "en"); // Psalm 151 doesn't exist
 BibleLinker::linkify("3 John 1-16", "en"); // 3 John 15-16 don't exist
 /*
  * <a href="https://www.bible.com/bible/111/PSA.150..NIV">Psalm 150</a>; 151
  * <a href="https://www.bible.com/bible/111/3JN.1.1-14.NIV">3 John 1-16</a>
  */

Inline tags are tolerated

 BibleLinker::linkify("<span>John</span> 15:<span style='color:blue'>5</span>-6", "en"); // John 15:5-6
 /*
  * <span><a href="https://www.bible.com/bible/111/JHN.15.5-6.NIV">John 15:5-6</a></span><span style="color:blue"></span>
  */

Block-level tags are not respected like inline tags are

 BibleLinker::linkify("<p>Review John 15</p><p>:5</p>", "en"); // John 15 (not John 15:5)
 /*
  * <p>Review <a href="https://www.bible.com/bible/111/JHN.15..NIV">John 15</a></p><p>:5</p>
  */

Supported Languages

English (default translation: NIV)
Spanish (default translation: RVR1960)
French (default translation: LSG)
Portuguese (default translation: NVI)

Including In Your Project

run composer require church-renewal/bible-linker

Usage Examples

use ChurchRenewal\BibleLinker\BibleLinker;

/**
 * @param string - a two character language ID
 * @return bool - true if language is supported by Bible Linker
 */
BibleLinker::isLanguageSupported('es')
/*
 * true
 */

/**
 * @param string - must be HTML encoded
 * @param string - a two character language ID
 * @param array - optional: associative array of attributes to be added to the A tag
 * @return array - assocative array with keys:
 *     'new':                   int - number of new links inserted into content
 *     'alternative':           int - number of translations found in content which couldn't be found, but have known alternatives
 *     'unknown':               int - number translations found in content which couldn't be found on Bible.com
 *     'unknownTranslations':   array - an array of strings of the unknown translations
 *     'html':                  string - the content with links inserted
 *     'errors' :               array - an associative array of parsing errors; each key is the string that failed, each value is the error code
 */
BibleLinker::linkify('Psalm 119:105', 'en', ['class' => 'verse', 'target' => '_blank']);
/*
 * [
 *     'new' => 1
 *     'alternative' => 0
 *     'unknown' => 0
 *     'unknownTranslations' => []
 *     'html' => '<a href="https://www.bible.com/bible/111/PSA.119.105.NIV" class="verse" target="_blank">Psalm 119:105</a>',
 *     'errors' => []
 * ]
 */

Known Limitations

HTML content must be HTML-encoded. E.g. output from something like TinyMCE will work fine.

 // good
 BibleLinker::linkify(htmlentities("Hébreux 12:2"), "fr");
 BibleLinker::linkify("H&eacute;breux 12:2", "fr");

 // bad
 BibleLinker::linkify("Hébreux 12:2", "fr");

Verses must be separated by commas

 // good
 BibleLinker::linkify("Psalm 119:105, 106", "en");

 // bad
 BibleLinker::linkify("Psalm 119:105 & 106", "en");

Chapters must be separated by semi-colons

 // good
 BibleLinker::linkify("Psalm 119; 120", "en");

 // bad
 BibleLinker::linkify("Psalm 119, 120", "en");

Translations must be surrounded by parentheses

 // good
 BibleLinker::linkify("Psalm 119:105 (ESV)", "en");

 // bad
 BibleLinker::linkify("Psalm 119:105 ESV", "en");

Cannot specify more than one translation

 // good
 BibleLinker::linkify("Psalm 118 (NASB); Psalm 119:105 (ESV)", "en");

 // bad
 BibleLinker::linkify("Psalm 118 (NASB); 119:105 (ESV)", "en");

Running Tests In Development

Install Docker

./runtests.sh

church-renewal / bible-linker

Maintainers

Details