{"id":14363701,"url":"https://github.com/alexandre-daubois/phikl","last_synced_at":"2025-04-01T16:48:45.311Z","repository":{"id":223533308,"uuid":"759882948","full_name":"alexandre-daubois/phikl","owner":"alexandre-daubois","description":"🥒 Apple's Pkl bridge for PHP","archived":false,"fork":false,"pushed_at":"2024-06-13T09:26:01.000Z","size":78,"stargazers_count":29,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T06:53:33.199Z","etag":null,"topics":["apple","bridge","configuration","configuration-as-code","language","pickle","pkl"],"latest_commit_sha":null,"homepage":"https://pkl-lang.org","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/alexandre-daubois.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2024-02-19T14:16:11.000Z","updated_at":"2024-09-02T19:28:06.000Z","dependencies_parsed_at":"2024-06-13T12:06:46.622Z","dependency_job_id":null,"html_url":"https://github.com/alexandre-daubois/phikl","commit_stats":null,"previous_names":["alexandre-daubois/phikl"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-daubois%2Fphikl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-daubois%2Fphikl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-daubois%2Fphikl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexandre-daubois%2Fphikl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexandre-daubois","download_url":"https://codeload.github.com/alexandre-daubois/phikl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246674099,"owners_count":20815681,"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","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":["apple","bridge","configuration","configuration-as-code","language","pickle","pkl"],"created_at":"2024-08-27T17:01:24.256Z","updated_at":"2025-04-01T16:48:45.277Z","avatar_url":"https://github.com/alexandre-daubois.png","language":"PHP","funding_links":[],"categories":["PHP"],"sub_categories":[],"readme":"🥒 Phikl - Apple's Pkl Bridge for PHP\n=====================================\n\n[![PHPUnit](https://github.com/alexandre-daubois/phikl/actions/workflows/ci.yaml/badge.svg)](https://github.com/alexandre-daubois/phikl/actions/workflows/ci.yaml)\n\nPhikl (pronounced \"_fickle_\") is a PHP binding for Apple's PKL language. This library uses the official PKL CLI tool from Apple and\nprovides a PHP interface to it.\n\n## Installation\n\nYou can install this library using composer:\n\n```bash\ncomposer require alexandre-daubois/phikl\n```\n\nThe CLI tool must be installed on your system. You can either install it manually and set the `PKL_CLI_BIN`\nenvironment variable to the path of the binary or use the `install` subcommand of the `pkl` command to download\nthe latest supported version of the PKL CLI tool into the `vendor/bin` directory.\n\n```bash\nvendor/bin/phikl install\n```\n\nYou can also set the download location by using the `--location` option:\n\n```bash\nvendor/bin/phikl install --location=/usr/local/bin\n```\n\nIf you do so, you must set the `PKL_CLI_BIN` environment variable to the path of the binary.\n\n## Usage\n\n⚠️ If you plan to use this tool in production, it is highly recommended [to cache the PKL modules](#Caching).\n\n### Using the CLI tool\n\nThis package offers a CLI tool to interact with the PKL CLI tool. You can use the `phikl` command to interact with the\nPKL CLI tool, among other things.\n\nHere are some examples of how to use the `phikl` command:\n\n```bash\n# Install the PKL CLI tool\nvendor/bin/phikl install\n\n# Update/Force install the last supported PKL CLI tool\nvendor/bin/phikl update\n\n# Print current PKL CLI tool version\nvendor/bin/phikl version\n\n# Evaluate one or many PKL file\nvendor/bin/phikl eval config/simple.pkl config/nested.pkl\n```\n\n### Using Pkl in PHP\n\nThe main way to use this library is to evaluate PKL code. You can do this by using the `evaluate` method of the\n`Pkl` class.\n\n#### Basic Usage with PklModule\n\nLet's say you have the following PKL code:\n\n```pkl\n/// config/simple.pkl\n\nname = \"Pkl: Configure your Systems in New Ways\"\nattendants = 100\nisInteractive = true\namountLearned = 13.37\n```\n\nYou can evaluate this code like this:\n\n```php\nuse Phikl\\Pkl;\n\n$module = Pkl::eval('config/simple.pkl');\n\n// you can then interact with the module\necho $module-\u003eget('name'); // Pkl: Configure your Systems in New Ways\necho $module-\u003eget('attendants'); // 100\necho $module-\u003eget('isInteractive'); // true\necho $module-\u003eget('amountLearned'); // 13.37\n```\n\nThis also works with nested modules:\n\n```pkl\n/// config/nested.pkl\n\nwoodPigeon {\n    name = \"Common wood pigeon\"\n    diet = \"Seeds\"\n    taxonomy {\n        species = \"Columba palumbus\"\n    }\n}\n```\n\n```php\nuse Phikl\\Pkl;\n\n$module = Pkl::eval('config/nested.pkl');\n\n// you can then interact with the module\necho $module-\u003eget('woodPigeon')-\u003eget('name'); // Common wood pigeon\necho $module-\u003eget('woodPigeon')-\u003eget('diet'); // Seeds\necho $module-\u003eget('woodPigeon')-\u003eget('taxonomy')-\u003eget('species'); // Columba palumbus\n```\n\n#### Cast to other types\n\nYou can cast the values to other types using the `cast` method with a class\nrepresenting your data. Let's take the following PKL code:\n\n```pkl\nmyUser {\n    id = 1\n    name = \"John Doe\"\n    address {\n        street = \"123 Main St\"\n        city = \"Springfield\"\n        state = \"IL\"\n        zip = \"62701\"\n    }\n}\n```\n\nYou can cast this to a `User` class like this:\n\n```php\nuse Phikl\\Pkl;\n\nclass User\n{\n    public int $id;\n    public string $name;\n    public Address $address;\n}\n\nclass Address\n{\n    public string $street;\n    public string $city;\n    public string $state;\n    public string $zip;\n}\n\n$module = Pkl::eval('config/user.pkl');\n$user = $module-\u003eget('myUser')-\u003ecast(User::class);\n```\n\nYou can also pass `User::class` as the second argument to the `eval` method. This will automatically cast the module to\nthe given class. Beware that it returns an array indexed by the PKL instance name:\n\n```php\nuse Phikl\\Pkl;\n\n// ...\n\n$user = Pkl::eval('config/user.pkl', User::class)['myUser'];\n```\n\n#### The `PklProperty` Attribute\n\nYou can use the `PklProperty` attribute to specify the name of the property in the PKL file. This is useful when the\nproperty name in the PKL file is different from the property name in the PHP class. Let's take the following PKL code:\n\n```pkl\nmyUser {\n    id = 1\n    name = \"John Doe\"\n    address {\n        street = \"123 Main St\"\n        city = \"Springfield\"\n        state = \"IL\"\n        zip = \"62701\"\n    }\n}\n```\n\nYou can define a `User` class like this:\n\n```php\nuse Phikl\\PklProperty;\n\nclass User\n{\n    #[PklProperty('id')]\n    public int $userId;\n\n    #[PklProperty('name')]\n    public string $userName;\n\n    public Address $address;\n}\n```\n\nWhen casting, the `PklProperty` attribute will be used to map the property name in the PKL file to the property\nname in the PHP class.\n\n## Caching\n\nYou can (**and should**) cache the PKL modules to improve performance. This is especially useful when evaluating the same PKL file\nmultiple times.\n\n**⚠️ Using Phikl with the cache avoids the PKL CLI tool to be executed to evaluate modules and should be done when deploying your application for better performances.**\n\n### Warmup the Cache\n\nYou can use the `warmup` command to dump the PKL modules to a cache file by default. Phikl will then use the cache file automatically when evaluating a PKL file. If the PKL file is not found in the cache, Phikl will evaluate the PKL file on the go.\n\nPhikl will go through all `.pkl` files of your project and dump them to the cache file.\n\nHere's an example of how to use the `warmup` command:\n\n```bash\nvendor/bin/phikl warmup\n\n# you can also specify the file if you want to use a custom location\n# don't forget to set the `PHIKL_CACHE_FILE` environment variable\nvendor/bin/phikl warmup --cache-file=cache/pkl.cache\n```\n\nIf you need to validate a cache file, you can do so by using the `validate-cache` command:\n\n```bash\nvendor/bin/phikl validate-cache\n\n# optionally, set the `PHIKL_CACHE_FILE` environment variable\n# or use the `--cache-file` option\nvendor/bin/phikl validate-cache --cache-file=.cache/.phikl\n```\n\nHere are a few things to note about Phikl cache:\n\n- You can disable the cache by calling `Pkl::toggleCache(false)`, which is useful for development but highly discouraged in production\n- Phikl will automatically refresh the cache if a PKL module is modified since last warmup\n- Any corrupted cache entry will be automatically refreshed\n\n### Cache Backends\n\nIf you have your own cache system, you can use the `Pkl::setCache()` method to set the cache system to use. You can pass it any instance of compliant PSR-16 cache system implementing `Psr\\SimpleCache\\CacheInterface`. This is useful you want to use, for example, a Redis server as a cache system for your Pkl modules.\n\nPhikl comes with the following cache backends:\n\n * `PersistentCache`, which is the default one used by Phikl. It uses a file to store the cache ;\n * `ApcuCacheAdapter`, which uses the APCu extension to store the cache in memory ;\n * `MemcachedCacheAdapter`, which uses the Memcached extension to store the cache in memory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandre-daubois%2Fphikl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexandre-daubois%2Fphikl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexandre-daubois%2Fphikl/lists"}