{"id":21542452,"url":"https://github.com/amethyst-php/relation-schema","last_synced_at":"2025-08-23T23:04:44.117Z","repository":{"id":56946911,"uuid":"216081164","full_name":"amethyst-php/relation-schema","owner":"amethyst-php","description":null,"archived":false,"fork":false,"pushed_at":"2024-04-05T10:59:59.000Z","size":106,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-05T01:35:59.153Z","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/amethyst-php.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":"2019-10-18T18:05:16.000Z","updated_at":"2024-03-28T19:28:16.000Z","dependencies_parsed_at":"2025-01-24T08:41:15.857Z","dependency_job_id":"4d176687-ea70-482f-b8c0-adbacf45cdca","html_url":"https://github.com/amethyst-php/relation-schema","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amethyst-php%2Frelation-schema","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amethyst-php%2Frelation-schema/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amethyst-php%2Frelation-schema/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amethyst-php%2Frelation-schema/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amethyst-php","download_url":"https://codeload.github.com/amethyst-php/relation-schema/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244130281,"owners_count":20402753,"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":[],"created_at":"2024-11-24T05:09:41.292Z","updated_at":"2025-03-17T23:51:47.479Z","avatar_url":"https://github.com/amethyst-php.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Relation Schema\r\n\r\n[![Action Status](https://github.com/amethyst-php/relation-schema/workflows/Test/badge.svg)](https://github.com/amethyst-php/relation-schema/actions)\r\n[![Amethyst](https://img.shields.io/badge/package-Amethyst-7e57c2)](https://github.com/amethyst-php/amethyst)\r\n\r\nCreate your own custom relations between Eloquent Models without altering the code.\r\n\r\n# Requirements\r\n\r\n- PHP from 8.2 and later\r\n\r\n## Installation\r\n\r\nYou can install it via [Composer](https://getcomposer.org/) by typing the following command:\r\n\r\n```bash\r\ncomposer require amethyst/relation-schema\r\n```\r\n\r\nThe package will automatically register itself.\r\n\r\n## Initialization\r\n\r\nAdd `app('amethyst.relation-schema')-\u003eboot();` in any ServiceProvider in the method `boot`\r\n\r\n## Usage\r\n\r\nA simple usage looks like this\r\n```php\r\nuse Symfony\\Component\\Yaml\\Yaml;\r\n\r\napp('amethyst')-\u003eget('relation-schema')-\u003ecreateOrFail([\r\n    'name'    =\u003e 'parent',\r\n    'type'    =\u003e 'BelongsTo',\r\n    'data'    =\u003e 'foo',\r\n    'payload' =\u003e Yaml::dump([\r\n        'target' =\u003e 'bar',\r\n    ]),\r\n]);\r\n\r\n```\r\nHere's a list of all attributes with a brief explanation:\r\n- name: The name of the relation. Can be only alphanumeric and it must start with a letter\r\n- description: An optional field that will help to describe the relation \r\n- type: The type of the relation. Values: `BelongsTo`, `HasMany`, `HasOne`, `MorphTo`, `MorphToMany`, `MorphToOne`, `MorphMany`\r\n- data: The name of the data this relation start with. If a `Book` is related to an `Author` through the relation `BelongsTo` named `author`, then `book` is the data\r\n- payload: A sets of information used to define better the relation, this changes based on the type of the relation. For example in a `BelongsTo` relation you'll neet a target, in the previous example `Author` is the target. \r\n\r\nWhenever refering to any model, we will call it by name. For e.g. `\\App\\Models\\Customer` will be `customer`. [More info](https://github.com/amethyst-php/core)\r\n\r\nKeep in mind that this is an [Amethyst Package](https://github.com/amethyst-php/amethyst), if you wish to see the full list of available features and customization please check [core](https://github.com/amethyst-php/core)\r\n\r\n## Relationships\r\n\r\nAs said before, based on the `type` attribute, `payload` must have a different sets of value. It uses Yaml for the serialization, so for all examples we will use a `Symfony\\Component\\Yaml\\Yaml` to convert from array to Yaml.\r\n\r\nMost of relation uses the laravel-defined convention of names, such as `foreignKey` or `ownerKey`.\r\n\r\n### BelongsTo\r\n\r\nStarting with the most simple relation, `BelongsTo`. It requires only the `target` parameter that indicate to which Model we are relating.\r\n\r\nYou can also set the `foreignKey` option.\r\n\r\nSo for example this new record\r\n```php\r\nuse Symfony\\Component\\Yaml\\Yaml;\r\n\r\napp('amethyst')-\u003eget('relation-schema')-\u003ecreateOrFail([\r\n    'name'    =\u003e 'parent',\r\n    'type'    =\u003e 'BelongsTo',\r\n    'data'    =\u003e 'foo',\r\n    'payload' =\u003e Yaml::dump([\r\n        'target' =\u003e 'bar',\r\n        'foreignKey' =\u003e 'foreign_key'\r\n    ])\r\n]);\r\n```\r\nis the exact same thing like this\r\n\r\n```php\r\nuse Illuminate\\Database\\Eloquent\\Relations\\BelongsTo;\r\n\r\nclass Foo\r\n{\r\n\tpublic function parent(): BelongsTo\r\n\t{\r\n\t\treturn $this-\u003ebelongsTo(Bar::class, 'foreign_key');\r\n\t}\r\n}\r\n\r\n```\r\n\r\n### HasMany and HasOne\r\n\r\nThe inverse relationship of BelongsTo. They behave exactly the same.\r\n\r\nBeside the `target` you can set `foreignKey` and `localKey`.\r\n\r\nNow let's look an example of the same relationship in `BelongsTo` but inverted\r\n\r\n```php\r\nuse Symfony\\Component\\Yaml\\Yaml;\r\n\r\napp('amethyst')-\u003eget('relation-schema')-\u003ecreateOrFail([\r\n    'name'    =\u003e 'children',\r\n    'type'    =\u003e 'HasMany',\r\n    'data'    =\u003e 'bar',\r\n    'payload' =\u003e Yaml::dump([\r\n        'target' =\u003e 'foo',\r\n        'foreignKey' =\u003e 'foreign_key',\r\n        'localKey' =\u003e 'local_key'\r\n    ]),\r\n]);\r\n```\r\nWill result in:\r\n```php\r\nuse Illuminate\\Database\\Eloquent\\Relations\\HasMany;\r\n\r\nclass Bar\r\n{\r\n\tpublic function children(): HasMany\r\n\t{\r\n\t\treturn $this-\u003ebelongsTo(Foo::class, 'foreign_key', 'local_key');\r\n\t}\r\n}\r\n\r\n```\r\n\r\nBut wait, there's more! You can create relations with a custom subfilter. Say for example that having a `customer` and `invoice` you want to create a relation that retrieve all `invoices` with `status`:`paid` from your customer.\r\n\r\nYou can add another parameter called `filter` in the `payload`.\r\n\r\nSo having something like this: `filter: \"status eq 'paid'\"`. You can also use auto joins here, so for e.g. a query like: only the invoice that contains `Maintenance` in the name, will result in `filter: \"status eq 'paid' and items.name ct 'Maintenance'\"`.\r\n\r\nLimitation: You cannot insert in the filter the same relation you're currently defining\r\n### ManyToMany and BelongsToMany\r\nNot yet implemented.\r\n\r\n### MorphTo\r\n\r\nSimilar to`BelongsTo` it doesn't require a `target`, instead it requires a `foreignKey` that in this case means the name of the field\r\n\r\n### MorphToMany and MorphToOne\r\n\r\nWIP\r\n\r\n### MorphMany\r\n\r\nWIP \r\n\r\n## Api\r\n\r\nThere are no additional routes in this package, only the default provided by the [core](https://github.com/amethyst-php/core).\r\n\r\n## Testing\r\n\r\n- Clone this repository\r\n- Copy the default `phpunit.xml.dist` to `phpunit.xml`\r\n- Change the environment variables as you see fit\r\n- Launch `./vendor/bin/phpunit`\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famethyst-php%2Frelation-schema","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famethyst-php%2Frelation-schema","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famethyst-php%2Frelation-schema/lists"}