Initial Commit

README.md

@@ -0,0 +1,63 @@
+# IMPHP - Debug
+___
+
+Debugging a project in PHP is not very easy, compared to the debugging done in things like a `Java` project. The biggest problem with PHP, which is also some of the performance benefits, is that most errors will be hidden away until the exact moment that you try to execute it. Even though you may have executed that exact file or even method/function a 100 times before, successfully.
+
+__Example__
+
+```php
+use namespace\SomeClasss;
+
+function someTest() {
+    try {
+        // Something that cold raise exceptions
+
+    } catch (Exception $e) {
+        throw new SomeClass( $e->getMessage() );
+    }
+}
+```
+
+The code above could perform perfectly 1000 times, so long as an exception is never raised in the code being executed. But, as soon as an exception is raised and the code tries to invoke `SomeClass`, it will fail. Why? Because it will be trying to use `\SomeClass` rather than `\namespace\SomeClass` because of the extra `s` that was added in the `use` clause. We are including `SomeClassS` and not `SomeClass`. However PHP will never know about this small mistake until the exact moment that it tries to use it. This is a feature in PHP and not a mistake, because without allowing this, things like autoloading would either not be available or it would auto-include every single class file that was being used, even if they are not needed.
+
+But regardless of why PHP is working the way it is, it still raises a lot of problems when building projects. The above example is just one of many small and common mistakes that can linger in code for ages, before finally breaking a system after it has been published. One could test this during Unit Testing, but even such tests can miss a problem or two. The more debugging done, the more issues will be found.
+
+This package was built for internal use cases when working on IMPHP, to catch the most common issues:
+
+ - General code syntax error.
+ - Validate enherited datatypes.
+ - Validate all datatypes being used in a file.
+ - Check `use` clauses to see if they are even used in the code.
+ - ...
+
+This package does not contain the entire test suides used by IMPHP, because those are specific to those projects. But it does include the main tools powering them.
+
+### Full Documentation
+
+You can view the [Full Documentation](docs/base.md) to lean more about what this offers.
+
+### Installation
+
+__Using .phar library__
+
+```sh
+wget https://github.com/IMPHP/debug/releases/download/<version>/imphp-debug.phar
+```
+
+```php
+require "imphp-debug.phar";
+
+...
+```
+
+__Clone via git__
+
+```sh
+git clone https://github.com/IMPHP/debug.git imphp/debug/
+```
+
+__Composer _(Packagist)___
+
+```sh
+composer require imphp/debug
+```

bootstrap.php

@@ -0,0 +1,34 @@
+<?php declare(strict_types=1);
+/*
+ * This file is part of the IMPHP Project: https://github.com/IMPHP
+ *
+ * Copyright (c) 2018 Daniel Bergløv, License: MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+ * and associated documentation files (the "Software"), to deal in the Software without restriction,
+ * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+ * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+ * THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+if (is_file("composer.json")) {
+    $json = json_decode(file_get_contents("composer.json"), true);
+
+    if (!empty($json["version"]) && !empty($json["name"])) {
+        eval('namespace im; const ' . str_replace("/", "_", strtoupper(trim($json["name"]))) . ' = "' . trim($json["version"]) . '";');
+
+    } else {
+        throw new Exception("Failed to set bootstrap constants");
+    }
+
+} else {
+    throw new Exception("Failed to set bootstrap constants");
+}

composer.json

@@ -0,0 +1,24 @@
+{
+    "name": "imphp/debug",
+    "license": "MIT",
+    "description": "Debug tools that among other things, can scan a project for general issues like missing references, type checking, lint errors and more.",
+    "type": "library",
+    "version": "1.0.0",
+
+    "authors": [
+        {
+            "name": "Daniel Bergløv"
+        }
+    ],
+
+    "require": {
+        "php": ">=8.0.0"
+    },
+
+    "autoload": {
+        "psr-4": {
+            "im\\": "src/"
+        },
+        "files": ["bootstrap.php"]
+    }
+}

docs/debug-Debugger-addSourceTree.md

@@ -0,0 +1,19 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: addSourceTree
+ > im\debug\Debugger
+____
+
+## Description
+Add a source directory
+
+This will be used to resolve dependencies when doing things
+like `trialRun` and such.
+
+## Synopsis
+```php
+public addSourceTree(string $path): void
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| path | Directory path with additional dependencies |

docs/debug-Debugger-compileClassMap.md

@@ -0,0 +1,24 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: compileClassMap
+ > im\debug\Debugger
+____
+
+## Description
+Scan a directory and build a class map
+
+This method will build a complete class map from a directory.
+It will scan each file and extract any class information from it,
+and add it's path to the map.
+
+## Synopsis
+```php
+public static compileClassMap(string $path, bool $fullPath = FALSE): array
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| path | The directory to scan |
+| fullPath | Add complete paths to the class map.<br />Otyherwise the paths will be relative to $path |
+
+## Return
+An assoc array with class names as key and file paths as value

docs/debug-Debugger-prop_E_ERROR.md

@@ -0,0 +1,8 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: E_ERROR
+ > im\debug\Debugger
+____
+
+## Synopsis
+```php
+public E_ERROR = 500
+```

docs/debug-Debugger-prop_E_INTERNAL.md

@@ -0,0 +1,8 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: E_INTERNAL
+ > im\debug\Debugger
+____
+
+## Synopsis
+```php
+public E_INTERNAL = -1
+```

docs/debug-Debugger-prop_E_WARNING.md

@@ -0,0 +1,8 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: E_WARNING
+ > im\debug\Debugger
+____
+
+## Synopsis
+```php
+public E_WARNING = 501
+```

docs/debug-Debugger-trialRun.md

@@ -0,0 +1,22 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: trialRun
+ > im\debug\Debugger
+____
+
+## Description
+Run a file in a sandboxed process
+
+This will setup an autoloader using the source trees
+within this instance and run a script in a sub-process.
+
+If no error occure, the method will return the output
+as an array where each element represent a line of the output.
+
+## Synopsis
+```php
+public trialRun(string $file): array
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| file | The file to run |

docs/debug-Debugger-validateImports.md

@@ -0,0 +1,24 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: validateImports
+ > im\debug\Debugger
+____
+
+## Description
+Validate class imports
+
+This method will report any missing or unused imports.
+It checks all class references, resolved using the import information
+in the file, and looks it up in iether the produced source tree or among
+PHP's internal classes.
+
+It will also look at all the defined imports to see if they are actually
+being used within the file.
+
+## Synopsis
+```php
+public validateImports(string $file): bool
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| file | The file to check |

docs/debug-Debugger-validateSyntax.md

@@ -0,0 +1,22 @@
+# [Debug](debug.md) / [Debugger](debug-Debugger.md) :: validateSyntax
+ > im\debug\Debugger
+____
+
+## Description
+Run a lint test and validate the code syntax.
+
+This is a lightweigth version of `trialRun()`.
+It's not gonna be as aggressive, but it will catch any
+syntax error in the file.
+
+ > This method does not require any additional source tree to work  
+
+## Synopsis
+```php
+public validateSyntax(string $file, bool $strict = FALSE): bool
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| file | The file to check |

docs/debug-Debugger.md

@@ -0,0 +1,47 @@
+# [Debug](debug.md) / Debugger
+ > im\debug\Debugger
+____
+
+## Description
+Provides tools to debug code files
+
+This class has a few tools to do basic debug checks on a file.
+This is a great way to catch a lot of the basic errors like missing
+imports, type error in class names, syntax error etc.
+
+This does not replace a proper Unit Testing setup, but it can be useful
+for fixing basic issues before running additional tests.
+
+## Synopsis
+```php
+final class Debugger {
+
+    // Constants
+    public E_INTERNAL = -1
+    public E_WARNING = 501
+    public E_ERROR = 500
+
+    // Methods
+    public static compileClassMap(string $path, bool $fullPath = FALSE): array
+    public addSourceTree(string $path): void
+    public validateSyntax(string $file, bool $strict = FALSE): bool
+    public validateImports(string $file): bool
+    public trialRun(string $file): array
+}
+```
+
+## Constants
+| Name | Description |
+| :--- | :---------- |
+| [__Debugger :: E\_INTERNAL__](debug-Debugger-prop_E_INTERNAL.md) |  |
+| [__Debugger :: E\_WARNING__](debug-Debugger-prop_E_WARNING.md) |  |
+| [__Debugger :: E\_ERROR__](debug-Debugger-prop_E_ERROR.md) |  |
+
+## Methods
+| Name | Description |
+| :--- | :---------- |
+| [__Debugger :: compileClassMap__](debug-Debugger-compileClassMap.md) | Scan a directory and build a class map  This method will build a complete class map from a directory |
+| [__Debugger :: addSourceTree__](debug-Debugger-addSourceTree.md) | Add a source directory  This will be used to resolve dependencies when doing things like `trialRun` and such |
+| [__Debugger :: validateSyntax__](debug-Debugger-validateSyntax.md) | Run a lint test and validate the code syntax |
+| [__Debugger :: validateImports__](debug-Debugger-validateImports.md) | Validate class imports  This method will report any missing or unused imports |
+| [__Debugger :: trialRun__](debug-Debugger-trialRun.md) | Run a file in a sandboxed process  This will setup an autoloader using the source trees within this instance and run a script in a sub-process |

docs/debug-DocumentFile-__construct.md

@@ -0,0 +1,17 @@
+# [Debug](debug.md) / [DocumentFile](debug-DocumentFile.md) :: __construct
+ > im\debug\DocumentFile
+____
+
+## Description
+Create a new DocumentFile
+
+## Synopsis
+```php
+public __construct(string $file, bool $onlyHeaders = FALSE)
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| file | Path to a php file |
+| onlyHeaders | Only extract headers like openTag and define information |

docs/debug-DocumentFile-fromCode.md

@@ -0,0 +1,16 @@
+# [Debug](debug.md) / [DocumentFile](debug-DocumentFile.md) :: fromCode
+ > im\debug\DocumentFile
+____
+
+## Description
+Return an instance from a code string
+
+## Synopsis
+```php
+public static fromCode(string $code): self
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| code | Code to process, incl. PHP open tags |

docs/debug-DocumentFile-fromResource.md

@@ -0,0 +1,16 @@
+# [Debug](debug.md) / [DocumentFile](debug-DocumentFile.md) :: fromResource
+ > im\debug\DocumentFile
+____
+
+## Description
+Return an instance from a code resource
+
+## Synopsis
+```php
+public static fromResource($stream): self
+```
+
+## Parameters
+| Name | Description |
+| :--- | :---------- |
+| stream | A resource with code to process |

docs/debug-DocumentFile-getClass.md

@@ -0,0 +1,8 @@
+# [Debug](debug.md) / [DocumentFile](debug-DocumentFile.md) :: getClass
+ > im\debug\DocumentFile
+____
+
+## Synopsis
+```php
+public getClass(string $name): null|im\debug\entities\Clazz
+```

docs/debug-DocumentFile-getClasses.md

@@ -0,0 +1,8 @@
+# [Debug](debug.md) / [DocumentFile](debug-DocumentFile.md) :: getClasses
+ > im\debug\DocumentFile
+____
+
+## Synopsis
+```php
+public getClasses(): array
+```

docs/debug-DocumentFile-getConstant.md

@@ -0,0 +1,8 @@
+# [Debug](debug.md) / [DocumentFile](debug-DocumentFile.md) :: getConstant
+ > im\debug\DocumentFile
+____
+
+## Synopsis
+```php
+public getConstant(string $name): null|im\debug\entities\Property
+```