{"id":17170303,"url":"https://github.com/nahid/presento","last_synced_at":"2025-04-13T16:07:50.495Z","repository":{"id":57023330,"uuid":"203593646","full_name":"nahid/presento","owner":"nahid","description":"Presento - Transformer \u0026 Presenter Package for PHP","archived":false,"fork":false,"pushed_at":"2020-07-28T06:28:39.000Z","size":37,"stargazers_count":74,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-13T16:07:43.773Z","etag":null,"topics":["array","php","php7","presenter","transformer"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nahid.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-21T13:46:57.000Z","updated_at":"2025-02-06T04:38:39.000Z","dependencies_parsed_at":"2022-08-23T13:51:01.046Z","dependency_job_id":null,"html_url":"https://github.com/nahid/presento","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpresento","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpresento/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpresento/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nahid%2Fpresento/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nahid","download_url":"https://codeload.github.com/nahid/presento/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248741206,"owners_count":21154255,"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":["array","php","php7","presenter","transformer"],"created_at":"2024-10-14T23:29:30.068Z","updated_at":"2025-04-13T16:07:50.471Z","avatar_url":"https://github.com/nahid.png","language":"PHP","readme":"# Presento\n\nA data preparing and presenting package for PHP.\n\n## Why Presento?\n\n**Presento** is a simple but powerful tools for preparing and presenting data.\nWhen we build an API based application, we need to _transform_ the data before _present_ it through the response. This package will make this task easier for you. \n\nNot clear enough? \n\nDon't worry, you'll get better idea from the [Usage examples](#usage).\n\n### Requirements\n\n```text\nPHP \u003e= 7.0\next-json\n```\n\n## Installation\n\nInstall the package using composer:\n\n```text\ncomposer require nahid/presento\n```\n\n## Usage\n\n**Presento** serves two important purposes. one is **Presentation** and another is **Transformation** of the data. \n\nLet's see some examples to understand how to use it.\n\nWe'll use the following data set to show the examples. Let's say we've this data set fetched from some data source and need to do some transformation or modifications before sending it to the response.\n\n```php\n$response = [\n    \"id\" =\u003e 123456,\n    \"name\" =\u003e \"Nahid Bin Azhar\",\n    \"email\" =\u003e \"talk@nahid.im\",\n    \"type\" =\u003e 1,\n    \"is_active\" =\u003e 1,\n    \"created_at\" =\u003e \"2018-01-02 02:03:04\",\n    \"updated_at\" =\u003e \"2018-01-02 02:03:04\",\n    \"deleted_at\" =\u003e \"2018-01-02 02:03:04\",\n    \"projects\" =\u003e [\n        [\n            \"id\" =\u003e 1,\n            \"name\" =\u003e \"Laravel Talk\",\n            \"url\"   =\u003e \"https://github.com/nahid/talk\",\n            \"license\" =\u003e \"CC0\",\n            \"created_at\" =\u003e \"2016-02-02 02:03:04\"\n        ],\n        [\n            \"id\" =\u003e 2,\n            \"name\" =\u003e \"JsonQ\",\n            \"url\"   =\u003e \"https://github.com/nahid/jsonq\",\n            \"license\" =\u003e \"MIT\",\n            \"created_at\" =\u003e \"2018-01-02 02:03:04\"\n        ]\n    ]\n];\n```\n\n#### Simple Presentation Example\nWhen sending this data to the API response, we only want to send the `id`, `name`, `email`, `type`, `is_active` and `projects`. \n\nWe can simply do that by preparing a Presenter for this like following.\n\n```php\n// UserPresenter.php\n\nclass UserPresenter extends \\Nahid\\Presento\\Presenter\n{\n    public function present() : array\n    {\n        return [\n            'id',\n            'name',\n            'email',\n            'type',\n            'is_active',\n            'projects',\n        ];\n    }\n}\n```\n\nAnd you might already guessed how to use it, right? \n\n```php\n$user = new UserPresenter($response);\ndump($user-\u003eget());\n```\n\nIt'd show something like this:\n\n```php\n[\n    \"id\" =\u003e 123456,\n    \"name\" =\u003e \"Nahid Bin Azhar\",\n    \"email\" =\u003e \"talk@nahid.im\",\n    \"type\" =\u003e 1,\n    \"is_active\" =\u003e 1,\n    \"projects\" =\u003e [\n        [\n            \"id\" =\u003e 1,\n            \"name\" =\u003e \"Laravel Talk\",\n            \"url\"   =\u003e \"https://github.com/nahid/talk\",\n            \"license\" =\u003e \"CC0\",\n            \"created_at\" =\u003e \"2016-02-02 02:03:04\"\n        ],\n        [\n            \"id\" =\u003e 2,\n            \"name\" =\u003e \"JsonQ\",\n            \"url\"   =\u003e \"https://github.com/nahid/jsonq\",\n            \"license\" =\u003e \"MIT\",\n            \"created_at\" =\u003e \"2018-01-02 02:03:04\"\n        ]\n    ]\n]\n```\n\nPretty simple, right?\n\n#### 'key' aliasing in Presentation example\n\nLet's say you want to change some of the 'key' to something different, like the `id` key to `user_id` . \nHow can you do that? \n\nJust do the following.\n\n```php\n// UserPresenter.php\nclass UserPresenter extends \\Nahid\\Presento\\Presenter\n{\n    public function present() : array\n    {\n        return [\n            'user_id' =\u003e 'id',\n            'name',\n            'email',\n            'type',\n            'is_active',\n        ];\n    }\n}\n```\n\nThis will format the data like following:\n\n```php\n[\n    \"user_id\" =\u003e 123456,\n    \"name\" =\u003e \"Nahid Bin Azhar\",\n    \"email\" =\u003e \"talk@nahid.im\",\n    \"type\" =\u003e 1,\n    \"is_active\" =\u003e 1,\n]\n```\n\n\n#### Deep traversing in Presentation example\n\nYou can easily dive deep and get data from a nested level by using `.` (dot) notation. \n\nLet's say you want to show the `name` of the first package as the `top_package` in your data. \n\nThis is how you do it.\n\n```php\n// UserPresenter.php\nclass UserPresenter extends \\Nahid\\Presento\\Presenter\n{\n    public function present() : array\n    {\n        return [\n            'id',\n            'name',\n            'email',\n            'type',\n            'is_active',\n            'top_package' =\u003e 'projects.0.name',\n            'projects',\n        ];\n    }\n}\n``` \n\nThis will format the data like this:\n\n```php\n[\n    \"id\" =\u003e 123456,\n    \"name\" =\u003e \"Nahid Bin Azhar\",\n    \"email\" =\u003e \"talk@nahid.im\",\n    \"type\" =\u003e 1,\n    \"is_active\" =\u003e 1,\n    \"top_package\" =\u003e \"Laravel Talk\",\n    \"projects\" =\u003e [\n        [\n            \"id\" =\u003e 1,\n            \"name\" =\u003e \"Laravel Talk\",\n            \"url\"   =\u003e \"https://github.com/nahid/talk\",\n            \"license\" =\u003e \"CC0\",\n            \"created_at\" =\u003e \"2016-02-02 02:03:04\"\n        ],\n        [\n            \"id\" =\u003e 2,\n            \"name\" =\u003e \"JsonQ\",\n            \"url\"   =\u003e \"https://github.com/nahid/jsonq\",\n            \"license\" =\u003e \"MIT\",\n            \"created_at\" =\u003e \"2018-01-02 02:03:04\"\n        ]\n    ]\n]\n```\n\nNotice the `top_package` key in the data.\n\n\n#### Simple Transformer Example\n\nLet's say our UserPresenter is like this:\n\n```php\n// UserPresenter.php\nclass UserPresenter extends \\Nahid\\Presento\\Presenter\n{\n    public function present() : array\n    {\n        return [\n            'user_id' =\u003e 'id',\n            'name',\n            'email',\n            'type',\n            'is_active',\n        ];\n    }\n}\n``` \nAnd we want to show the `user_id` as _hashed_ value instead of an incremental integer value as it is in our database. That means we want to transform the `user_id`.\n\nTo do that we need to create a Transformer Class like this:\n\n```php\n// UserTransformer.php\nclass UserTransformer extends \\Nahid\\Presento\\Transformer\n{\n    public function getUserIdProperty($value)\n    {\n        return md5($value);\n    }\n}\n```\n\nNotice that, as we will transform the `user_id` property, we named our transformer method as `getUserIdProperty`. So, if you want to transform the `name` property too, you need to just create another method in this class named `getNameProperty` and add the transformation logic inside it.\n\nNow, we need to let know the _Presenter_ how to _Transform_ the data before presenting it. \n\nTo do that, we need to add the following method in the `UserPresenter` class.\n\n```php\n// UserPresenter.php\npublic function transformer()\n{\n    return UserTransformer::class;\n}\n```\n\nSo, our final output would be:\n\n```php\n[\n    \"user_id\" =\u003e \"e10adc3949ba59abbe56e057f20f883e\",\n    \"name\" =\u003e \"Nahid Bin Azhar\",\n    \"email\" =\u003e \"talk@nahid.im\",\n    \"type\" =\u003e 1,\n    \"is_active\" =\u003e 1,\n]\n```\n\nAin't it easy, mate?\n\n#### Nested Presenter Example\n\nYou might notice that there is a collection of `projects` in our data set. If each `project` is a separate resource, you might have a separate Presenter for that. Like this:\n\n```php\n// ProjectPresenter.php\nclass ProjectPresenter extends \\Nahid\\Presento\\Presenter\n{\n    public function present() : array\n    {\n        return [\n            'id',\n            'name',\n            'url',\n            'license',\n            'created_at',\n        ];\n    }\n\n    public function transformer()\n    {\n        return ProjectTransformer::class;\n    }\n}\n```\n\nCan you use this Presenter for each of the `projects` in the _Users_ data? \n\nHell Yeah! Just do this:\n\n```php\n// UserPresenter.php\npublic function present() : array\n{\n    return [\n        'user_id' =\u003e 'id',\n        'name',\n        'email',\n        'type',\n        'is_active',\n        'projects' =\u003e [ProjectPresenter::class =\u003e ['projects']],\n    ];\n}\n```\n\nNow, each of the `project` in the list of `projects` in _Users_ will be presented as defined in the `ProjectPresenter`.\n\n\n#### Base Data format conversion Example\n\nAs you have seen that, the data set we have used till now is a plain _Array_. But some times it might not be the case. You might need to work with something different, like **Eloquent Model** of Laravel framework. \nIn that case, you can simply add a method called `convert` in your _Presenter_ to convert the Base data to an Array format.\n\nLet's see an Example:\n\n```php\n// UserPresenter.php\npublic function convert($data)\n{\n    if ($data instanceof Model) {\n        return $data-\u003etoArray();\n    }\n\n    return $data;\n}\n```\n\nThat's it. \n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnahid%2Fpresento","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnahid%2Fpresento","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnahid%2Fpresento/lists"}