Implementation of Contract::getEventLogs() and improved general comments and error messages

README.md

@@ -185,6 +185,10 @@ $constructorData = $contract->bytecode($bytecode)->getData($params);
 
 // get function data
 $functionData = $contract->at($contractAddress)->getData($functionName, $params);
+
+//get event log data 
+//$fromBlock and $toBlock are optional, default to 'latest' and accept block numbers integers
+$events = $contract->getEventLogs($eventName, $fromBlock, $toBlock);
 ```
 
 # Assign value to outside scope(from callback scope to outside scope)

src/Contract.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * This file is part of web3.php package.
+ * This file is part of the web3.php package.
  * 
  * (c) Kuan-Cheng,Lai <alk03073135@gmail.com>
  * 
@@ -11,7 +11,8 @@
 
 namespace Web3;
 
-use InvalidArgumentException;
+use \InvalidArgumentException;
+use \RuntimeException;
 use Web3\Providers\Provider;
 use Web3\Providers\HttpProvider;
 use Web3\RequestManagers\RequestManager;
@@ -175,7 +176,7 @@ public function __construct($provider, $abi, $defaultBlock = 'latest')
     // public function __call($name, $arguments)
     // {
     //     if (empty($this->provider)) {
-    //         throw new \RuntimeException('Please set provider first.');
+    //         throw new RuntimeException('Please set provider first.');
     //     }
     //     $class = explode('\\', get_class());
     //     if (preg_match('/^[a-zA-Z0-9]+$/', $name) === 1) {
@@ -267,6 +268,7 @@ public function setDefaultBlock($defaultBlock)
 
     /**
      * getFunctions
+     * get an array of all methods in the loaded contract
      *
      * @return array
      */
@@ -277,6 +279,7 @@ public function getFunctions()
 
     /**
      * getEvents
+     * get an array of all events (and their inputs) in the loaded contract
      *
      * @return array
      */
@@ -368,14 +371,15 @@ public function setToAddress($address)
 
     /**
      * at
+     * set the address of the deployed contract to make calls to
      * 
      * @param string $address
      * @return $this
      */
     public function at($address)
     {
         if (AddressValidator::validate($address) === false) {
-            throw new InvalidArgumentException('Please make sure address is valid.');
+            throw new InvalidArgumentException('Please make sure the contract address is valid.');
         }
         $this->toAddress = AddressFormatter::format($address);
 
@@ -391,7 +395,7 @@ public function at($address)
     public function bytecode($bytecode)
     {
         if (HexValidator::validate($bytecode) === false) {
-            throw new InvalidArgumentException('Please make sure bytecode is valid.');
+            throw new InvalidArgumentException('Please make sure the bytecode input is valid.');
         }
         $this->bytecode = Utils::stripZero($bytecode);
 
@@ -407,7 +411,7 @@ public function bytecode($bytecode)
     public function abi($abi)
     {
         if (StringValidator::validate($abi) === false) {
-            throw new InvalidArgumentException('Please make sure abi is valid.');
+            throw new InvalidArgumentException('Please make sure the abi input is valid.');
         }
         $abiArray = [];
         if (is_string($abi)) {
@@ -438,7 +442,7 @@ public function abi($abi)
 
     /**
      * new
-     * Deploy a contruct with params.
+     * Deploy a new contract, along with any relevant parameters for its constructor.
      * 
      * @param mixed
      * @return void
@@ -452,13 +456,13 @@ public function new()
 
             $input_count = isset($constructor['inputs']) ? count($constructor['inputs']) : 0;
             if (count($arguments) < $input_count) {
-                throw new InvalidArgumentException('Please make sure you have put all constructor params and callback.');
+                throw new InvalidArgumentException('Please make sure you have included all constructor parameters and a callback function.');
             }
             if (is_callable($callback) !== true) {
-                throw new \InvalidArgumentException('The last param must be callback function.');
+                throw new InvalidArgumentException('The last parameter must be a callback function.');
             }
             if (!isset($this->bytecode)) {
-                throw new \InvalidArgumentException('Please call bytecode($bytecode) before new().');
+                throw new InvalidArgumentException('Please call bytecode($bytecode) before new().');
             }
             $params = array_splice($arguments, 0, $input_count);
             $data = $this->ethabi->encodeParameters($constructor, $params);
@@ -480,7 +484,8 @@ public function new()
 
     /**
      * send
-     * Send function method.
+     * Send inputs to a specific method of the deployed contract 
+     * (interacts with chain data and can alter it: costs gas)
      * 
      * @param mixed
      * @return void
@@ -493,7 +498,7 @@ public function send()
             $callback = array_pop($arguments);
 
             if (!is_string($method)) {
-                throw new InvalidArgumentException('Please make sure the method is string.');
+                throw new InvalidArgumentException('Please make sure the method name is supplied as a string as the first parameter.');
             }
 
             $functions = [];
@@ -503,10 +508,10 @@ public function send()
                 }
             };
             if (count($functions) < 1) {
-                throw new InvalidArgumentException('Please make sure the method exists.');
+                throw new InvalidArgumentException('Please make sure the named method exists in the contract.');
             }
             if (is_callable($callback) !== true) {
-                throw new \InvalidArgumentException('The last param must be callback function.');
+                throw new InvalidArgumentException('The last parameter must be a callback function.');
             }
 
             // check the last one in arguments is transaction object
@@ -558,7 +563,7 @@ public function send()
                 break;
             }
             if (empty($data) || empty($functionName)) {
-                throw new InvalidArgumentException('Please make sure you have put all function params and callback.');
+                throw new InvalidArgumentException('Please make sure you have included all parameters of the method and a callback function.');
             }
             $functionSignature = $this->ethabi->encodeFunctionSignature($functionName);
             $transaction['to'] = $this->toAddress;
@@ -575,7 +580,8 @@ public function send()
 
     /**
      * call
-     * Call function method.
+     * Call a specific method of the deployed contract 
+     * (read-only, cannot alter chain data: does not cost gas)
      *
      * @param mixed
      * @return void
@@ -588,7 +594,7 @@ public function call()
             $callback = array_pop($arguments);
 
             if (!is_string($method)) {
-                throw new InvalidArgumentException('Please make sure the method is string.');
+                throw new InvalidArgumentException('Please make sure the method name is supplied as a string as the first parameter.');
             }
 
             $functions = [];
@@ -598,10 +604,10 @@ public function call()
                 }
             };
             if (count($functions) < 1) {
-                throw new InvalidArgumentException('Please make sure the method exists.');
+                throw new InvalidArgumentException('Please make sure the named method exists in the contract.');
             }
             if (is_callable($callback) !== true) {
-                throw new \InvalidArgumentException('The last param must be callback function.');
+                throw new InvalidArgumentException('The last parameter must be a callback function.');
             }
 
             // check the arguments
@@ -623,7 +629,7 @@ public function call()
                 break;
             }
             if (empty($data) || empty($functionName)) {
-                throw new InvalidArgumentException('Please make sure you have put all function params and callback.');
+                throw new InvalidArgumentException('Please make sure you have included all parameters of the method and a callback function.');
             }
             // remove arguments
             array_splice($arguments, 0, $paramsLen);
@@ -686,13 +692,13 @@ public function estimateGas()
                 $constructor = $this->constructor;
 
                 if (count($arguments) < count($constructor['inputs'])) {
-                    throw new InvalidArgumentException('Please make sure you have put all constructor params and callback.');
+                    throw new InvalidArgumentException('Please make sure you have included all constructor parameters and a callback function.');
                 }
                 if (is_callable($callback) !== true) {
-                    throw new \InvalidArgumentException('The last param must be callback function.');
+                    throw new InvalidArgumentException('The last parameter must be a callback function.');
                 }
                 if (!isset($this->bytecode)) {
-                    throw new \InvalidArgumentException('Please call bytecode($bytecode) before estimateGas().');
+                    throw new InvalidArgumentException('Please call bytecode($bytecode) before estimateGas().');
                 }
                 $params = array_splice($arguments, 0, count($constructor['inputs']));
                 $data = $this->ethabi->encodeParameters($constructor, $params);
@@ -706,7 +712,7 @@ public function estimateGas()
                 $method = array_splice($arguments, 0, 1)[0];
 
                 if (!is_string($method)) {
-                    throw new InvalidArgumentException('Please make sure the method is string.');
+                    throw new InvalidArgumentException('Please make sure the method name is supplied as a string as the first parameter.');
                 }
 
                 $functions = [];
@@ -716,10 +722,10 @@ public function estimateGas()
                     }
                 };
                 if (count($functions) < 1) {
-                    throw new InvalidArgumentException('Please make sure the method exists.');
+                    throw new InvalidArgumentException('Please make sure the named method exists in the contract.');
                 }
                 if (is_callable($callback) !== true) {
-                    throw new \InvalidArgumentException('The last param must be callback function.');
+                    throw new InvalidArgumentException('The last parameter must be a callback function.');
                 }
 
                 // check the last one in arguments is transaction object
@@ -771,7 +777,7 @@ public function estimateGas()
                     break;
                 }
                 if (empty($data) || empty($functionName)) {
-                    throw new InvalidArgumentException('Please make sure you have put all function params and callback.');
+                    throw new InvalidArgumentException('Please make sure you have included all parameters of the method and a callback function.');
                 }
                 $functionSignature = $this->ethabi->encodeFunctionSignature($functionName);
                 $transaction['to'] = $this->toAddress;
@@ -789,9 +795,9 @@ public function estimateGas()
 
     /**
      * getData
-     * Get the function method call data.
-     * With this function, you can send signed contract function transaction.
-     * 1. Get the funtion data with params.
+     * Get the contract method's call data.
+     * With this function, you can send signed contract method transactions.
+     * 1. Get the method data with parameters.
      * 2. Sign the data with user private key.
      * 3. Call sendRawTransaction.
      * 
@@ -808,10 +814,10 @@ public function getData()
                 $constructor = $this->constructor;
 
                 if (count($arguments) < count($constructor['inputs'])) {
-                    throw new InvalidArgumentException('Please make sure you have put all constructor params and callback.');
+                    throw new InvalidArgumentException('Please make sure you have included all constructor parameters and a callback function.');
                 }
                 if (!isset($this->bytecode)) {
-                    throw new \InvalidArgumentException('Please call bytecode($bytecode) before getData().');
+                    throw new InvalidArgumentException('Please call bytecode($bytecode) before getData().');
                 }
                 $params = array_splice($arguments, 0, count($constructor['inputs']));
                 $data = $this->ethabi->encodeParameters($constructor, $params);
@@ -820,7 +826,7 @@ public function getData()
                 $method = array_splice($arguments, 0, 1)[0];
 
                 if (!is_string($method)) {
-                    throw new InvalidArgumentException('Please make sure the method is string.');
+                    throw new InvalidArgumentException('Please make sure the method name is supplied as a string as the first parameter.');
                 }
 
                 $functions = [];
@@ -830,7 +836,7 @@ public function getData()
                     }
                 };
                 if (count($functions) < 1) {
-                    throw new InvalidArgumentException('Please make sure the method exists.');
+                    throw new InvalidArgumentException('Please make sure the named method exists in the contract.');
                 }
 
                 $params = $arguments;
@@ -849,12 +855,102 @@ public function getData()
                     break;
                 }
                 if (empty($data) || empty($functionName)) {
-                    throw new InvalidArgumentException('Please make sure you have put all function params and callback.');
+                    throw new InvalidArgumentException('Please make sure you have included all parameters of the method and a callback function.');
                 }
                 $functionSignature = $this->ethabi->encodeFunctionSignature($functionName);
                 $functionData = Utils::stripZero($functionSignature) . Utils::stripZero($data);
             }
             return $functionData;
         }
     }
+
+    /**
+     * getEventLogs
+     * 
+     * @param string $eventName
+     * @param string|int $fromBlock
+     * @param string|int $toBlock
+     * @return array
+     */
+    public function getEventLogs(string $eventName, $fromBlock = 'latest', $toBlock = 'latest')
+    {
+        //try to ensure block numbers are valid together
+        if ($fromBlock !== 'latest') {
+            if (!is_int($fromBlock) || $fromBlock < 1) {
+                throw new InvalidArgumentException('Please make sure fromBlock is a valid block number');
+            } else if ($toBlock !== 'latest' && $fromBlock > $toBlock) {
+                throw new InvalidArgumentException('Please make sure fromBlock is equal or less than toBlock');
+            }
+        }
+
+        if ($toBlock !== 'latest') {
+            if (!is_int($toBlock) || $toBlock < 1) {
+                throw new InvalidArgumentException('Please make sure toBlock is a valid block number');
+            } else if ($fromBlock === 'latest') {
+                throw new InvalidArgumentException('Please make sure toBlock is equal or greater than fromBlock');
+            }
+        }
+
+        $eventLogData = [];
+
+        //ensure the event actually exists before trying to filter for it
+        if (!array_key_exists($eventName, $this->events)) {
+            throw new InvalidArgumentException("'{$eventName}' does not exist in the ABI for this contract");
+        }
+
+        //indexed and non-indexed event parameters must be treated separately
+        //indexed parameters are stored in the 'topics' array
+        //non-indexed parameters are stored in the 'data' value
+        $eventParameterNames = [];
+        $eventParameterTypes = [];
+        $eventIndexedParameterNames = [];
+        $eventIndexedParameterTypes = [];
+
+        foreach ($this->events[$eventName]['inputs'] as $input) {
+            if ($input['indexed']) {
+                $eventIndexedParameterNames[] = $input['name'];
+                $eventIndexedParameterTypes[] = $input['type'];
+            } else {
+                $eventParameterNames[] = $input['name'];
+                $eventParameterTypes[] = $input['type'];
+            }
+        }
+
+        $numEventIndexedParameterNames = count($eventIndexedParameterNames);
+
+        //filter through log data to find any logs which match this event (topic) from
+        //this contract, between these specified blocks (defaulting to the latest block only)
+        $this->eth->getLogs([
+            'fromBlock' => (is_int($fromBlock)) ? '0x' . dechex($fromBlock) : $fromBlock,
+            'toBlock' => (is_int($toBlock)) ? '0x' . dechex($toBlock) : $toBlock,
+            'topics' => [$this->ethabi->encodeEventSignature($this->events[$eventName])],
+            'address' => $this->toAddress
+        ],
+        function ($error, $result) use (&$eventLogData, $eventParameterTypes, $eventParameterNames, $eventIndexedParameterTypes, $eventIndexedParameterNames) {
+            if ($error !== null) {
+                throw new RuntimeException($error->getMessage());
+            }
+
+            foreach ($result as $object) {
+                //decode the data from the log into the expected formats, with its corresponding named key
+                $decodedData = array_combine($eventParameterNames, $this->ethabi->decodeParameters($eventParameterTypes, $object->data));
+
+                //decode the indexed parameter data
+                for ($i = 0; $i < $numEventIndexedParameterNames; $i++) {
+                    //topics[0] is the event signature, so we start from $i + 1 for the indexed parameter data
+                    $decodedData[$eventIndexedParameterNames[$i]] = $this->ethabi->decodeParameters([$eventIndexedParameterTypes[$i]], $object->topics[$i + 1])[0];
+                }
+
+                //include block metadata for context, along with event data
+                $eventLogData[] = [
+                    'transactionHash' => $object->transactionHash,
+                    'blockHash' => $object->blockHash,
+                    'blockNumber' => hexdec($object->blockNumber),
+                    'data' => $decodedData
+                ];
+            }
+        });
+
+        return $eventLogData;
+    }
 }