first commit

.github/workflows/php.yml

@@ -0,0 +1,76 @@
+name: Run PHP Tests and Code Quality Tools
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+  schedule:
+      # Also run  every Sunday at midnight
+      - cron: '0 0 * * 0'
+
+jobs:
+  build:
+
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+        matrix:
+            php: [8.0, 7.4, 7.3]
+# prefer-lowest is causing unit tests to fail when php 7.2 is run against PHPunit 7.x, 
+# PHPUnit 8.x is the latest stable release that supports PHP 7.2 and that runs fine
+#            dependency-version: [prefer-lowest, prefer-stable]
+            dependency-version: [prefer-stable]
+            os: [ubuntu-18.04, ubuntu-20.04]
+            include:
+                - os: ubuntu-18.04
+                  php: 7.3
+                - os: ubuntu-18.04
+                  php: 7.4
+                - os: ubuntu-18.04
+                  php: 8.0
+                - os: ubuntu-20.04
+                  php: 7.4
+                - os: ubuntu-20.04
+                  php: 8.0
+            exclude:
+                - os: ubuntu-20.04
+                  php: 7.3
+
+    name: PHP-${{ matrix.php }} - ${{ matrix.dependency-version }} - ${{ matrix.os }}
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v2
+
+    - name: Setup PHP
+      uses: shivammathur/setup-php@v2
+      with:
+          php-version: ${{ matrix.php }}
+          ini-values: pcre.jit=0, pcre.backtrack_limit=9999999, pcre.recursion_limit=9999999
+          coverage: none
+
+    - name: PHP version
+      run: php -v
+
+    - name: Composer version
+      run: composer --version
+
+    - name: Validate composer.json and composer.lock
+      run: composer validate
+
+    - name: Install Dependencies
+      run: composer update --${{ matrix.dependency-version }} --prefer-dist --no-interaction --no-progress
+
+    # Add a test script to composer.json, for instance: "test": "vendor/bin/phpunit"
+    # Docs: https://getcomposer.org/doc/articles/scripts.md
+    - name: Run PHPUnit Test Suite
+      run: vendor/bin/phpunit
+
+    - name: Run Rector
+      # Run rector for PHP 7.X but not 8.0, rector is currently blowing up with PHP 8.0
+      if: matrix.php != '8.0'
+      run: vendor/bin/rector process src --dry-run
+
+    - name: Run Psalm
+      run: vendor/bin/psalm

.gitignore

@@ -0,0 +1,28 @@
+/composer.lock
+*~
+*.bak
+Thumbs.db
+desktop.ini
+.DS_Store
+.buildpath
+.project
+.settings
+*.tmproj
+build
+.idea
+.phpunit.result.cache
+
+nbproject/
+/nbproject/
+/nbproject/*
+/nbproject/*.*
+/nbproject/*/
+
+vendor/
+/vendor/
+/vendor/*
+/vendor/*.*
+/vendor/*/
+
+composer.lock
+phpunit.xml

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2020, Rotexsoft
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,19 @@
+# Function Execution Timer
+
+[![PHP Tests and Code Quality Tools](https://github.com/rotexsoft/function-execution-timer/workflows/Run%20PHP%20Tests%20and%20Code%20Quality%20Tools/badge.svg)](https://github.com/rotexsoft/function-execution-timer/actions?query=workflow%3A%22Run+PHP+Tests+and+Code+Quality+Tools%22)  
+[![Release](https://img.shields.io/github/release/rotexsoft/function-execution-timer.png?style=flat-square)](https://github.com/rotexsoft/function-execution-timer/releases/latest)   
+[![License](https://img.shields.io/badge/license-BSD-brightgreen.png?style=flat-square)](https://github.com/rotexsoft/function-execution-timer/blob/master/LICENSE)   
+
+
+A simple PHP library for tracking the total amount of time a function / method takes to execute and return result(s) (if any).
+
+
+## Installation 
+
+**Via composer:** (Requires PHP 7.3+ or PHP 8.0+). 
+
+    composer require rotexsoft/function-execution-timer
+
+## Introduction
+
+A simple PHP library for tracking the total amount of time a function / method takes to execute and return result(s) (if any).

TODO.md

@@ -0,0 +1,16 @@
+# Things To Do
+* ~~Implement Generic Classes implementing the various interfaces~~ [DONE]
+* Implement a profiling mechanism for debugging purposes that shows an audit trail of how permissions were calculated when isAllowed is invoked
+* ~~Write unit tests~~ [DONE]
+* ~~Hook up to travis and other code monitoring services~~ [DONE]
+* Implement a separate package illustrating how to implement Owner, User and Group level permission enforcement
+* Check other stuff in my other projects that could be of value in this one
+* ~~Update class diagram once package is stable~~ [DONE]
+* Document using this package using acl examples from existing application and even using examples from the zend packages.
+   * Add guidelines on how to customize this package to suit various requirements like the 
+   Owner, User and Group level permission enforcement described above.
+* Add a logging mechanism to log how permissions are calculated in isAllowed to a string
+   * This will require adding a getAuditTrail method to the collection interfaces and classes and also to the VersatileAcl class
+       * When setLogger is called on an instance of VersatileAcl, it will inject that logger into every collection it creates
+* Submit to packagist once it's well done.
+* When PHP 7.4 becomes the minimum version, change all class properties to typed properties and edit **rector.php** to include PHP 7.4 rules

composer.json

@@ -0,0 +1,28 @@
+{
+    "name": "rotexsoft/function-execution-timer",
+    "description": "A simple PHP library for tracking the total amount of time a function / method takes to execute and return result(s) (if any).",
+    "license": "BSD-3-Clause",
+    "keywords": [ "function", "functions", "method", "methods",  "profiler", "profiling", "benchmark", "benchmarks", "benchmarking", "execution", "time", "execution time"],
+    "homepage": "https://github.com/rotexsoft/function-execution-timer",
+    "authors": [
+        {
+            "name": "Rotimi Adegbamigbe",
+            "email": "[email protected]"
+        }
+    ],
+    "require": {
+        "php": ">=7.3.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^9.0",
+        "php-coveralls/php-coveralls": "^2.0",
+        "rector/rector": "^0.8.56",
+        "vimeo/psalm": "^4.3"
+    },
+    "autoload": {
+        "classmap": [ "src/", "tests/" ]
+    },
+    "scripts": {
+        "test": "vendor/bin/phpunit --coverage-text"
+    }
+}

index.php

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<!--
+To change this license header, choose License Headers in Project Properties.
+To change this template file, choose Tools | Templates
+and open the template in the editor.
+-->
+<html>
+    <head>
+        <meta charset="UTF-8">
+        <title></title>
+    </head>
+    <body>
+        <?php
+        // put your code here
+        ?>
+    </body>
+</html>

phpunit.xml.dist

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="./tests/bootstrap.php" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+  <coverage>
+    <include>
+      <directory suffix=".php">./src</directory>
+    </include>
+    <exclude/>
+    <report>
+      <clover outputFile="build/logs/clover.xml"/>
+      <html outputDirectory="build/coverage" lowUpperBound="35" highLowerBound="70"/>
+    </report>
+  </coverage>
+  <testsuites>
+    <testsuite name="function-execution-timer">
+      <directory>./tests</directory>
+    </testsuite>
+  </testsuites>
+  <logging>
+    <junit outputFile="build/logs/junit.xml"/>
+  </logging>
+</phpunit>

psalm.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<psalm
+    errorLevel="4"
+    resolveFromConfigFile="true"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="src" />
+        <ignoreFiles>
+            <directory name="vendor" />
+        </ignoreFiles>
+    </projectFiles>
+</psalm>

rector.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Core\Configuration\Option;
+use Rector\Php74\Rector\Property\TypedPropertyRector;
+use Rector\Set\ValueObject\SetList;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (ContainerConfigurator $containerConfigurator): void {
+    // get parameters
+    $parameters = $containerConfigurator->parameters();
+
+    // Define what rule sets will be applied
+    $parameters->set(Option::SETS, [
+        SetList::DEAD_CODE,
+        SetList::PHP_72,
+        SetList::PHP_73,
+        //SetList::PHP_74,
+        //SetList::PHP_80,
+        SetList::PERFORMANCE,
+    ]);
+
+    // get services (needed for register a single rule)
+    // $services = $containerConfigurator->services();
+
+    // register a single rule
+    // $services->set(TypedPropertyRector::class);
+};

src/FunctionExecutionTimer.php

@@ -0,0 +1,74 @@
+<?php
+declare(strict_types=1);
+
+namespace FunctionExecutionTimer;
+
+/**
+ * 
+ * A class that can be used to call any function or method while tracking the execution time of each call
+ *
+ * @author rotex
+ */
+class FunctionExecutionTimer extends ObjectifiedCallable {
+
+    /**
+     * Holds execution stats for all function / method calls across all instances of this class
+     * 
+     * @var array
+     */
+    protected static $benchmarks = [];
+
+    /**
+     * Executes function / method registered on an instance of this class
+     * 
+     * @param mixed $args arguments to pass to the function / method to be executed
+     * 
+     * @return mixed result returned from executing function / method registered on an instance of this class
+     */
+    public function __invoke(...$args) {
+
+        $startTime = \microtime(true);
+
+        $result = parent::__invoke(...$args);
+
+        $endTime = \microtime(true);
+
+        static::$benchmarks[] = [
+            'function' => $this->methodName,
+            'args' => $args,
+            'start_time' => $startTime,
+            'end_time' => $endTime,
+            'total_execution_time_in_seconds' => ($endTime - $startTime),
+            'return_value' => $result,
+        ];
+
+        return $result;
+    }
+
+    /**
+     * Return an array containing execution stats for all functions / methods called via all instances of this class
+     * 
+     * @return array an array containing execution stats for all functions / methods called via all instances of this class
+     */
+    public static function getBenchmarks(): array {
+
+        return static::$benchmarks;
+    }
+
+    /**
+     * Executes a callable 
+     * 
+     * @param string $funcName a name of your choosing (for the callable to be executed) that adheres to PHP method naming rules
+     * @param callable $funcImplementation the callable to be executed
+     * @param mixed $args arguments required by the callable to be executed
+     * 
+     * @return mixed
+     */
+    public static function callFunc(
+        string $funcName, callable $funcImplementation,  ...$args
+    ) {
+        $funcObj = (new self($funcName, $funcImplementation));
+
+        return $funcObj(...$args);
+    }
+}