PHPH1 elephant logo
×

Explorer Settings

Welcome To PHPH1

  • PHPH1 elephant logo

  • What is PHPH1?

    • A learning tool for developers on the Harmony v2 Node API. It allows you to test every API method using real world input and see how a direct JSON request is formatted as well as how the JSON return data is formatted for each request. On top of this, it provides simplified javascript examples of how to make API requests and retrieve data. It also includes built in documentation for each method describing their input variables and output data. Just browse to the method you want to learn about using the methods menu at the top right of the page. I would suggest taking a look below at how to use the entire explorer first.

    • A PHP wrapper class for the Harmony v2 Node API that allows other languages to make Harmony V2 Node API calls without worrying about input validation or properly formatting the JSON request.

    • A PHP wrapper class for the Harmony v2 Node API that can be used in your own PHP + whatever driven project.

  • What is required to run PHPH1

    • A web host with PHP installed as well as the PHP_CURL extension installed and enabled

    • An SSL (https://) host. WARNING! RUNNING PHPH1 WITHOUT SSL IS A HUGE SECURITY RISK, DO NOT DO IT!

  • How do I integrate this into my project?

    • First suggestion is to start by using the full class package with the API explorer interface (what you are looking at now) included. It will guide you in sending requests to the class wrapper interface.

    • The full package is designed to be called by any language that can pull data from a web request using POST or GET. Check out the Javascript examples provided in the method output pages.

    • If you are a PHP developer, there is a mini PHPH1 package that strips all the extraneous stuff from the Explorer out of the PHPH1 class and allows for an interface to validate and make calls to a Harmony API node.

  • Where do I get the package?

  • Where do I report issues?

Using this interface

  • Method Menu

    • At the right of the top floating menu is the methods dropdown menu. You can also search the methods in the menu.

      Methods Menu

  • Method Pages

    • The params/returns section is a clickable dropdown that shows what inputs the method uses as well as explains the method output data that can be expected.

      Params Click Bar

    • The form section is available when a method requires client input. The params/returns dropdown will tell you what each form item requires for input.

      Method form

    • The output section contains five sections of its own. Each section is clickable to view the output.

      • Harmony Node JSON RPC Request: Displays the actual JSON formatted request sent to the Harmony Node API Server

      • A BASIC javascript example of a Harmony Node JSON RPC Request using POST

      • PHPH1 GET request URL for this method: Displays a link to the phph1_call.php file that would be used by an external scripting language to retrieve results. The URL can be used as a template for making calls for that specific method.

      • A BASIC javascript example of a PHPH1 POST request

      • JSON return data: Displays the JSON data returned from the test request. Use this to ensure the method returns the data you expect to use in your project.

    • Output Bars

  • Setting Network and Shard

    • The hamburger menu has a "Settings" link to set the network and shard the client wants to use. The available networks and shards can be set in inc/config.php

      Settings Menu

    • The settings form has a network and shard dropdown. Select the network first and the available shards for that network will appear in the shard dropdown.

      Settings Form

    • You can see what network and shard is being used on the right side of the menu bar.

      Settings Status

  • Using the PHPH1 Call (phph1_call.php)

    • phph1_call.php is designed to accept formatted GET and POST requests by any language that can read JSON formatted data returns.

    • The explorer shows you an extremely basic sample javascript code for a POST request.

    • To see a little more robust example refer to jstest.html.

Full Package Setup

  • Download the package and extract it to a directory

    • You can get the package at the Github project releases page.

    • Extract the package and upload all files to your web host. The package contents can sit in your document root or any sub directory.

    • You will have to handle the archive a little differently depending on whether you downloaded the .zip or the .tar.gz file.

    • The .zip file, if extracted with no directory options will extract all the files to the current directory which can be messy. If using the zip file on a Linux/Unix machine, be sure to extract it into a directory where no other files exist or use the unzip -d option.

    • The tar.gz package will extract within a directory that matches the release name.

    • It is highly suggested whether using the zip or tar.gz, you extract the package outside of your project and then copy it to where you want it. This will ensure nothing gets accidentally overwritten.

  • Check and adjust the settings to your liking in inc/config.php

    • $phph1_debug

      Variable used to enable (set to 1) or disable (set to 0) API Explorer PHP debugging. Enabling this exposes many things to the client, I highly suggest not using it in a production environment unless it is a last resort. It also puts big ugly warnng header at the top of the pages so you are aware debugging is enabled.

    • $phph1_blockedaddr

      This array is used to block IP addresses if necessary. Just add an IP address to the array like the example and the code will use the $_SERVER['REMOTE_ADDR'] to see if users are blocked. If the $phph1_allowedaddr array is not empty, this array gets ignored

    • $phph1_allowedaddr

      This array is used to only allow specific IP Addresses. Just add an IP address to the array like the example and the code will use the $_SERVER['REMOTE_ADDR'] to make sure the request is allowed by the client. If this array has any values in it, the $phph1_blockedaddr is ingored due to redundancy. REMINDER! Usig this blocks all hosts except the hosts listed in this array.

    • $phph1_allowbigdata

      Some requests have a page index (page number) option. Included insome of those options is the ability to use -1 as the index page. When using -1 the data set returned could possibly be huge causing a massive load on the server. By default using the -1 option is disabled to prevent this from happening. You can enable -1 page requests here by setting $phph1_allowbigdata to 1

    • $phph1_apiaddresses

      This is a multi-dimensional array that holds the node and shard information. By default this array contains the official Harmony nodes but you can comment them out and add your own personal nodes as shown where the array is set. if you do add your own node address, be sure to also set $default_network and $default_shard as well

    • $default_network

      Sets the default network (also the network used by the rpc script). It MUST use a network listed in the $phph1_apiaddresses array. For example by default it is set to use "mainnet".

    • $default_shard

      Sets the default shard (also the shard used by the rpc script). It MUST use a shard listed in the $phph1_apiaddresses array. For example by default it is set to use "0".

    • $default_pagesize

      The default page size for methods that return multiple pages of data

    • $max_pagesize

      This is the maximum number of items per page when a method returns multiple pages of data. This prevents a client from reuesting large datasets in a single call which will put a heavy load on the web server.

    • $phph1_methods

      An array of the available methods. This is used to prevent a client from requesting a method that doesn'teist. You can use a PHP comment out individual lines to disable a method.

    • $sorted_Methods

      This is just the $phph1_methods array that has been sorted alphabetically so the front end dropdown menu makes some sense.

  • Browse to where you uploaded PHPH1 and go!

Limiting Client Requests

  • There are two different approaches available

    • You can allow everyone and block specific IP addresses using the $phph1_blockedaddr array in inc/config.php

    • You can block everyone and only allow specific IP addresses using the $phph1_allowedaddr array in inc/config.php.

  • Option 1: Allow everyone and block specific IP addresses

    • This option is automatically enabled once the first IP address is added to the $phph1_blockedaddr array

    • Leaving the $phph1_blockedaddr array empty disables this option

    • NOTE: This option is disabled if the $phph1_allowedaddr array contains any entries.

  • Option 2: Block everyone and only allow specific IP addresses

    • This option is automatically enabled once the first IP address is added to the $phph1_allowedaddr array

    • Leaving the $phph1_allowedaddr array empty disables this option

    • NOTE: Adding and IP address to this option disables the $phph1_blockedaddr array if it contains any entries. there is no reason to block if everyone but the allowed IP address[es] is blocked by default

Class Only

  • Download the package and extract it to a directory

    • You can get the package at the Github project releases page.

    • Extract the package and upload all files to your web host. The package contents can sit in your document root or any sub directory.

    • You will have to handle the archive a little differently depending on whether you downloaded the .zip or the .tar.gz file.

    • The .zip file, if extracted with no directory options will extract all the files to the current directory which can be messy. If using the zip file on a Linux/Unix machine, be sure to extract it into a directory where no other files exist or use the unzip -d option.

    • The tar.gz package will extract within a directory that matches the release name.

    • It is highly suggested whether using the zip or tar.gz, you extract the package outside of your project and then copy it to where you want it. This will ensure nothing gets accidentally overwritten.

  • Check and adjust the settings to your liking in inc/config.php

    • $phph1_apiaddresses

      This is a multi-dimensional array that holds the node and shard information. By default this array contains the official Harmony nodes but you can comment them out and add your own personal nodes as shown where the array is set. if you do add your own node address, be sure to also set $default_network and $default_shard as well

    • $default_network

      Sets the default network (also the network used by the rpc script). It MUST use a network listed in the $phph1_apiaddresses array. For example by default it is set to use "mainnet".

    • $default_shard

      Sets the default shard (also the shard used by the rpc script). It MUST use a shard listed in the $phph1_apiaddresses array. For example by default it is set to use "0".

    • $default_pagesize

      The default page size for methods that return multiple pages of data

    • $max_pagesize

      This is the maximum number of items per page when a method returns multiple pages of data. This prevents a client from reuesting large datasets in a single call which will put a heavy load on the web server.

  • Include the required files in your page (There is an example index.php for reference)

    • include('config.php');
include('phph1.php');

  • Create a PHPH1 class handle

    • $phph1 = new phph1($phph1_apiaddresses,$max_pagesize,$default_pagesize, $default_network, $default_shard);

  • Refer to the documentation for all of the methods and their required inputs.

    • Each method has a validation method that starts with val_ and the actual method that starts with hmyv2_

    • When running the validation methods, if there are errors they are stored in the class array variable errors, you can retrieve them as an array using $phph1->get_errors()
    • if($phph1->val_getBlockByNumber('26974649',TRUE,FALSE,TRUE,TRUE)){
	$blockdata = $phph1->hmyv2_getBlockByNumber('26974649',TRUE,FALSE,TRUE,TRUE);
	// This is just here to show you what output is available
	print_r($blockdata);
}else{
	// This is just here to show you what errors exist
	print_r($phph1->get_errors());
}

  • When running the hmyv2_ methods, data is returned in a JSON encoded format.

    • You can decode the data using PHP's json_decode(), but be warned, converting large data with PHP can put a heavy memory load on the server

    • You can decode the data by passing the PHP object off to javascript. This is the recommended way and performs seemingly well with large data returns.

    • <p>Epoch: <span id="block_epoch">Loading</span></p>

<p>Hash: <span id="block_hash">Loading</span></p>
      <?php
// Include the config and class
include('config.php');
include('phph1.php');

// Create the phph1 class handle
$phph1 = new phph1($phph1_apiaddresses,$max_pagesize,$default_pagesize, $default_network, $default_shard);

// Using hmyv2_getBlockByNumber with block number 26974649 as an example
if($phph1->val_getBlockByNumber('26974649',TRUE,FALSE,TRUE,TRUE)){
	
	// Make the API call
	$blockdata = $phph1->hmyv2_getBlockByNumber('26974649',TRUE,FALSE,TRUE,TRUE);
	
	// This line below is for debugging. Uncomment the line to see it
	// print_r($blockdata);
}else{
	// This line below is for debugging. Uncomment the line to see it
	// print_r($phph1->get_errors());
	
	// Iterate through the errors
	foreach($phph1->get_errors() as $anError){
		echo "<p>".$anError."<p>";
	}
}
?>

      <script>
// Notice I used the "block_hash" id so the text goes into the proper container defined above
var hash_id = document.getElementById("block_hash");

// Notice I used the "block_epoch" id so the text goes into the proper container defined above
var epoch_id = document.getElementById("block_epoch");

// This is where the PHP object gets injected into Javascript
var obj = <?=$blockdata?>;

// Put the block's hash data in the <p> container we defined above
hash_id.innerHTML = obj['result']['hash'];

// Put the block's epoch data in the <p> container we defined above
epoch_id.innerHTML = obj['result']['epoch'];

</script>

PHPH1 :: A Harmony ONE Node API PHP Class

Copyright © 2022 by Jason L Kolpin
Released under the GNU General Public License v3.0
Funded by a Bounty Grant provided by the Harmony ONE Team

GitHub Project Page :: Report A Bug

ILL_DIE_TRYING/PHPH1 Discord

Page generated in 0.002 seconds.