This tutorial is a basic introduction to PHP for anyone in the heritage community. It is an updated version of the Introduction to Coding appendix in my book Open Heritage Data.

What is PHP:

PHP: Hypertext Preprocessor is an open-source scripting language especially suited for web development (php.net). PHP script is executed on the server and does usually require a web server to run on. However, as you will see in this tutorial it is also possible to test your PHP scripts online without installing or hosting your own server. More on that later.

Why do I need PHP:

PHP is useful if you want to access and manipulate heritage datasets and present them in a webbrowser. You might have a database of heritage items or historic people that you want to publish online, or you may want to test and present an open heritage dataset in a new and interesting way on the web. PHP is very useful here.

Example of PHP code

The following is a selection of PHP that illustrated the possibilities and scripting lingo. If you are interested in learning more PHP there are a number of online tutorials available for free online. I personally always use W3Schools to look-up code snippets or learn new coding languages. You can also test the code below in an online PHP test environment – here I prefer phpfiddle.org as it allows you to test APIs too.

The PHP code is enveloped by <?php and ?> and comments can be written in blocks (surrounded by /* and */) or inline using // or # at the beginning of a new line of comments. PHP variables begin with $ and statements end with a semicolon.

<?php
/* first we declare
the variable $x and use it to
calculate the variable $y */
$x = 6;
$y = $x + 7; // the result is 13

# we can use PHP to print the result as a HTML top level header
echo "<h1>" . $y . "</h1>";

// we can create an array of artists
$artists = array("Anna", "Marie", "Anne");

// and use the foreach loop to display each artist with a line‐break after
foreach ($artists as $person) {
    echo "$person <br>";
}

// we can create a function to call a particular artist from the array
function callArtist($i) {
    $artists = array("Anna", "Marie", "Anne");
    echo "Hi $artists[$i]";
}

// and execute the function with the second person (array index = 1)
callArtist(1); // result is "Hi Marie"
?>

A basic list of Emily Brontë’s poems

In the following tutorial we will use the API at PoetryDB to list Emily Brontë‘s poems in a way that it can be used on a website. At PoetryDB there are further instructions on how to use the API which has different methods. Below are a couple of examples of methods that can be used to retrieve data from this API (%20 is HTTP code for a space):

If you click on the links you can see the data formatted as JSON (I will explain this in a later post). It can look a bit confusing at first but by using a code beautifier we can explore this JSON dataset in a more structured way. For example if we paste one of the links from above into codebeautify.org/jsonviewer each poem by Emily Brontë is placed in a numbered array (see above) with the data about the poem.

Now that we have our dataset containing the poem titles of Emily Brontë all we need is some PHP code that can transform this data from JSON into a HTML (post coming) list, which we can display on a website. The code will go through the following steps:

  1. It specifies the API URL in a variable ($api_URL).
  2. It imports the file content into a different variable ($json_file) using the file_get_contents() function.
  3. It decodes the JSON file into a third variable ($resource_array) using the json_decode() function.
  4. The variable ($resource_array) is then looped (using foreach loops) and each record is output temporarily into the variable $value.
  5. In the loop the title for each record is printed (using the echo statement). We use ‘->’ to indicate a path to the title for each poem. In this case it is simple because title is one level down from the poem level in the JSON tree structure (can be seen more clearly in the code beautifier).
  6. In the loop the HTML code for a horizontal line ‘<hr/>’ is printed for each record.
  7. Finally, the loop is closed and so is the PHP code.
<?php
// PHP test of PoetryDB
// (1) API URL 
$api_url = 'http://poetrydb.org/author/Emily%20Bronte';
// (2) Call the JSON file 
$json_file = file_get_contents($api_url);
// (3) Decode JSON file into a PHP array 
$resource_array = json_decode($json_file);
// (4) Loop through each record 
foreach ($resource_array as $value){
	// (5) Print title 
	echo $value->title;
	// (6) Print horizontal line
	echo "<hr/>"; 
} // (7) Loop end
?>



You can try and past the code into the code space of phpfiddle.org like I have done above and see the result by clicking Run– a list of the poem titles of Emily Brontë with horizontal lines between each.


This was a small example of how you can use PHP to retrieve heritage data from an API and transform it into something usable online. Here are a couple of ideas on how you can explore this more:

  • Try getting poems for a different author – remember to add %20 instead of a space in the URL, e.g. https://poetrydb.org/author/william%20shakespeare
  • Try using a different method to get titles that are about winter, e.g. https://poetrydb.org/title/winter
  • Try listing the authors names instead of the title of each poem, e.g. replace the path to title (->title) with the path to author (->author)
  • Try using different HTML code to style the list in a different way such as a HTML list (see code below), or if you are more comfortable with HTML try make dropdown menu or something else. 

<?php
// List example
$api_url = 'https://poetrydb.org/title/winter';
$json_file = file_get_contents($api_url);
$resource_array = json_decode($json_file);
echo "<ul>"; // Start HTML unnumbered list before the loop
foreach ($resource_array as $value){
	echo "<li>"; // Start each list item inside the loop
    echo $value->author;
	echo "</li>"; // End each list item 
} 
echo "</ul>"; // End HTML unnumbered list
?>



I would love to hear what you think about this subject on Twitter, LinkedIn or via email.

  • Tutorial: Basic PHP
  • Skill: Beginners