{"id":24764080,"url":"https://github.com/stillat/primitives","last_synced_at":"2025-10-11T13:30:17.620Z","repository":{"id":46347671,"uuid":"407719606","full_name":"Stillat/primitives","owner":"Stillat","description":"Converts string input into PHP runtime values.","archived":false,"fork":false,"pushed_at":"2024-08-15T14:46:56.000Z","size":462,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-19T18:32:05.456Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Stillat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"JohnathonKoster"}},"created_at":"2021-09-18T01:07:51.000Z","updated_at":"2025-09-15T16:25:23.000Z","dependencies_parsed_at":"2025-01-29T12:47:47.547Z","dependency_job_id":null,"html_url":"https://github.com/Stillat/primitives","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Stillat/primitives","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fprimitives","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fprimitives/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fprimitives/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fprimitives/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stillat","download_url":"https://codeload.github.com/Stillat/primitives/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stillat%2Fprimitives/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007341,"owners_count":26084282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-28T21:32:32.348Z","updated_at":"2025-10-11T13:30:17.614Z","avatar_url":"https://github.com/Stillat.png","language":"PHP","funding_links":["https://github.com/sponsors/JohnathonKoster"],"categories":[],"sub_categories":[],"readme":"![Primitives](banner.png)\n\nThis library provides a simple way to convert a string of simple values to their PHP runtime equivalents.\n\nThis library will parse the following types of values:\n\n* Numbers\n* Strings\n* Arrays\n* Associative arrays\n* true, false, null\n* Built-in PHP constants\n\nUnknown types will return `null` as their value.\n\n## Installation\n\nThis library can be installed with composer:\n\n```\ncomposer require stillat/primitives\n```\n\n## Example Usage\n\nTo use the library, create a new instance of the `Parser` class and call the `parseString` method:\n\n```php\n\u003c?php\n\nuse Stillat\\Primitives\\Parser;\n\n$parser = new Parser();\n\n$result = $parser-\u003eparseString('[1, 2, 3], \"some-string\", \"another\", [\"one\" =\u003e 1, \"two\" =\u003e 2]');\n\n```\n\nwould produce the following runtime result:\n\n```\narray(4) {\n  [0] =\u003e\n  array(3) {\n    [0] =\u003e\n    int(1)\n    [1] =\u003e\n    int(2)\n    [2] =\u003e\n    int(3)\n  }\n  [1] =\u003e\n  string(11) \"some-string\"\n  [2] =\u003e\n  string(7) \"another\"\n  [3] =\u003e\n  array(2) {\n    'one' =\u003e\n    int(1)\n    'two' =\u003e\n    int(2)\n  }\n}\n```\n\nThis library can also parse basic method details using the `parseMethod` method:\n\n```php\n\u003c?php\n\nuse Stillat\\Primitives\\Parser;\n\n$parser = new Parser();\n\n$result = $parser-\u003eparseMethod('methodName([1, 2, 3])');\n```\n\nwould produce the following runtime result:\n\n```\narray(2) {\n  [0] =\u003e\n  string(10) \"methodName\"\n  [1] =\u003e\n  array(1) {\n    [0] =\u003e\n    array(3) {\n      [0] =\u003e\n      int(1)\n      [1] =\u003e\n      int(2)\n      [2] =\u003e\n      int(3)\n    }\n  }\n}\n```\n\nInvalid input will produce a `null` value.\n\n## Parsing Nested Methods\n\nA more advanced alternative of `parseMethod` is the `parseMethods` method:\n\n```php\nuse Stillat\\Primitives\\Parser;\n\n$parser = new Parser();\n\n$result = $parser-\u003eparseMethods(\"randomElements(['a', 'b', 'c', 'd', 'e'], rand(1, 5))\"); \n```\n\nDetected method calls will be returned as instances of `Stillat\\Primitives\\MethodCall`. Each instance of this class\nwill contain the original method's name, as well as the parsed (and evaluated) runtime arguments. `parseMethods` will\n**not** run any methods for you.\n\n## Executing Runtime Methods\n\nPrimitives provides a utility `MethodRunner` class that can be used to execute the results of the `parseMethods` on any\ntarget class:\n\n```php\n\u003c?php\n\nuse Stillat\\Primitives\\Parser;\nuse Stillat\\Primitives\\MethodRunner;\n\n$parser = new Parser();\n$runner = new MethodRunner();\n\nclass MyClass {\n\n    public function sayHello($name)\n    {\n        return 'Hello, '.$name;\n    }\n\n}\n\n$myClassInstance = new MyClass();\n\n$methods = $parser-\u003eparseMethods(\"sayHello('Dave')\");\n$result = $runner-\u003erun($methods, $myClassInstance);\n\n```\n\nAfter the above code has executed, `$result` would contain the value `Hello, Dave`.\n\nImportant notes when using `MethodRunner`:\n\n* There must only be one root method call\n* If there is more than one root element, the `run` method returns `null`\n* `MethodRunner` does not check for method existence, allowing `__call` to be invoked\n\n## Calling Native PHP Functions\n\nThe internal method runner does not support calling native PHP functions. However, we can create a class instance\nthat can (and utilize whatever logic is appropriate for the current project to determine what is a \"safe\" function to call):\n\n```php\n\u003c?php\n\nuse Stillat\\Primitives\\Parser;\nuse Stillat\\Primitives\\MethodRunner;\n\n$parser = new Parser();\n$runner = new MethodRunner();\n\nclass Greeter {\n\n    public function sayHello($name)\n    {\n        return 'Hello, '.$name;\n    }\n\n}\n\nclass MethodTarget\n{\n\n    protected $instance;\n    protected $safePhpFunctions = [\n        'strtoupper'\n    ];\n\n    public function __construct()\n    {\n        $this-\u003einstance = new Greeter();\n    }\n\n    public function __call($name, $arguments)\n    {\n        // Replace with whatever logic makes sense. This approach\n        // utilizes an allowed list of functions, but using\n        // something like function_exists also works.\n        if (in_array($name, $this-\u003esafePhpFunctions)) {\n            return call_user_func($name, ...$arguments);\n        }\n\n        return call_user_func([$this-\u003einstance, $name], ...$arguments);\n    }\n\n}\n\n$instance = new MethodTarget();\n\n$result = $parser-\u003eparseMethods('sayHello(strtoupper(\"this is lowercase\"))');\n\n$methodResult = $runner-\u003erun($result, $instance);\n\n```\n\nAfter the above code has executed, `$methodResult` would contain the value `Hello, THIS IS LOWERCASE`. This approach works\nbecause we are making use of PHP's `__call` magic method to perform method overloading. When we attempt to call a method\non our class instance that does not exist, the `__call` method will receive the method name and arguments. If the list\nof safe functions contains the incoming method name, we will invoke it and return the results with the original arguments.\nIf our safe list does not contain the function, we default to attempting to call it on our target class instance.\n\n## Context Variables\n\nYou may also supply an array of contextual data that can be used when evaluating the input string. Context variables\nutilize the `$` syntax. The variable name in the input string will be replaced with their actual values once evaluated:\n\n```php\n\u003c?php\n\nuse Stillat\\Primitives\\Parser;\n\n$parser = new Parser();\n\n$context = [\n    'name' =\u003e 'Dave',\n    'city' =\u003e 'Anywhere'\n];\n\n$result = $parser-\u003eparseString('[$name, $city]', $context);\n```\n\nOnce the previous example has executed, `$result` would contain a value similar to:\n\n```\narray(1) {\n  [0] =\u003e\n  array(2) {\n    [0] =\u003e\n    string(4) \"Dave\"\n    [1] =\u003e\n    string(8) \"Anywhere\"\n  }\n}\n```\n\nNested variable paths can be utilized by using PHP's property fetcher syntax (array accessor syntax is not supported):\n\n```php\n\u003c?php\n\nuse Stillat\\Primitives\\Parser;\n\n$parser = new Parser();\n\n$context = [\n    'nested' =\u003e [\n        'arrays' =\u003e [\n            'test' =\u003e [\n                'name' =\u003e 'Dave',\n                'city' =\u003e 'Anywhere'\n            ]\n        ]\n    ]\n];\n\n$result = $parser-\u003eparseString('[$nested-\u003earrays-\u003etest-\u003ename,' .\n    '$nested-\u003earrays-\u003etest-\u003ecity]', $context);\n```\n\nLike before, the `$result` variable would contain a value similar to the following:\n\n```\narray(1) {\n  [0] =\u003e\n  array(2) {\n    [0] =\u003e\n    string(4) \"Dave\"\n    [1] =\u003e\n    string(8) \"Anywhere\"\n  }\n}\n```\n\n## License\n\nMIT License. See LICENSE.MD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fprimitives","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstillat%2Fprimitives","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstillat%2Fprimitives/lists"}