Squash previous commits

.github/FUNDING.yml

@@ -1 +1 @@
-github: :vendor_name
+github: clickbar

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +1,11 @@
 blank_issues_enabled: false
 contact_links:
   - name: Ask a question
-    url: https://github.com/:vendor_name/:package_name/discussions/new?category=q-a
+    url: https://github.com/clickbar/laravel-power-relations/discussions/new?category=q-a
     about: Ask the community for help
   - name: Request a feature
-    url: https://github.com/:vendor_name/:package_name/discussions/new?category=ideas
+    url: https://github.com/clickbar/laravel-power-relations/discussions/new?category=ideas
     about: Share ideas for new features
   - name: Report a security issue
-    url: https://github.com/:vendor_name/:package_name/security/policy
+    url: https://github.com/clickbar/laravel-power-relations/security/policy
     about: Learn how to notify us for sensitive bugs

CHANGELOG.md

@@ -1,3 +1,3 @@
 # Changelog
 
-All notable changes to `:package_name` will be documented in this file.
+All notable changes to `laravel-power-relations` will be documented in this file.

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) :vendor_name <[email protected]>
+Copyright (c) clickbar <[email protected]>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,70 +1,156 @@
-# :package_description
+# Laravel Custom Relations
 
-[![Latest Version on Packagist](https://img.shields.io/packagist/v/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/:vendor_slug/:package_slug/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/:vendor_slug/:package_slug/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/:vendor_slug/:package_slug/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/:vendor_slug/:package_slug/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
-[![Total Downloads](https://img.shields.io/packagist/dt/:vendor_slug/:package_slug.svg?style=flat-square)](https://packagist.org/packages/:vendor_slug/:package_slug)
-<!--delete-->
----
-This repo can be used to scaffold a Laravel package. Follow these steps to get started:
+[![Latest Version on Packagist](https://img.shields.io/packagist/v/53199186-ahawlitschek/laravel-power-relations.svg?style=flat-square)](https://packagist.org/packages/53199186-ahawlitschek/laravel-power-relations)
+[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/53199186-ahawlitschek/laravel-power-relations/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/53199186-ahawlitschek/laravel-power-relations/actions?query=workflow%3Arun-tests+branch%3Amain)
+[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/53199186-ahawlitschek/laravel-power-relations/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/53199186-ahawlitschek/laravel-power-relations/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
+[![Total Downloads](https://img.shields.io/packagist/dt/53199186-ahawlitschek/laravel-power-relations.svg?style=flat-square)](https://packagist.org/packages/53199186-ahawlitschek/laravel-power-relations)
 
-1. Press the "Use this template" button at the top of this repo to create a new repo with the contents of this skeleton.
-2. Run "php ./configure.php" to run a script that will replace all placeholders throughout all the files.
-3. Have fun creating your package.
-4. If you need help creating a package, consider picking up our <a href="https://laravelpackage.training">Laravel Package Training</a> video course.
----
-<!--/delete-->
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+Laravel provides some pretty good relations from scratch. If those relations do not fit the need, the community has provided a lot of other relation packages.
+Especially [staudenmeir](https://github.com/staudenmeir) did a lot if nice work on that end. However, in our projects we encountered the need of some really custom relations that could easily be expressed with an eloquent query, but not with default relations.
+Therefore, we created this package to give you the full control over your relations.
 
-## Support us
+## Introduction
+Sometimes it needs to be more custom.
+This package extends the default Laravel Relations with Relations that can be described by a query. 
 
-[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/:package_name.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/:package_name)
+For explanation purposes we consider the following model with a simple concatenated relation use case.
+(for cases like this you should also have a look  [eloquent-has-many-deep](https://github.com/staudenmeir/eloquent-has-many-deep) from staudenmeir).
+Even the example is quite simple, it should be able to represent the huge amount of possibilities that comes with custom relations.
+![model chain](art/models.png)
 
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
+Let's explorer the connection between Client and Task in the default Laravel way:
+```php
+$client = $task->order->project->client;
+$tasks = $client->projects->flatMap(fn(Project $project) => $project->order->flatMap(fn(Order $order) => $order->tasks));
+```
+
+Wouldn't it be cool to do stuff like this with only 1 single database query?
+```php
+$client = $task->client;
+$tasks = $client->tasks;
+```
+
+With Custom Relations you can do this with only one single Database Query.
 
-We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
 
 ## Installation
 
 You can install the package via composer:
 
 ```bash
-composer require :vendor_slug/:package_slug
+composer require clickbar/laravel-custom-relations
 ```
 
-You can publish and run the migrations with:
+## Preparing the Model
+In order to use the Custom Relations, you must use the ``HasCustomRelation`` trait:
 
-```bash
-php artisan vendor:publish --tag=":package_slug-migrations"
-php artisan migrate
-```
+```php
+use Clickbar\LaravelCustomRelations\Traits\HasCustomRelation;
 
-You can publish the config file with:
 
-```bash
-php artisan vendor:publish --tag=":package_slug-config"
+class Client extends Model{
+
+    use HasCustomRelation;
+
+    ...
+}
 ```
 
-This is the contents of the published config file:
+## Writing the Relation
+Like you know from Laravel, relations can return a collection of models or just one model.
+Therefore, this package has two Different Relations ``CustomRelation`` and ``CustomRelationSingle``.
 
+Let's look at our two examples from above: 
 ```php
-return [
-];
+class Task extends Model {
+
+    use HasCustomRelation;
+
+    public function client(): CustomRelationSingle {
+        return $this->customRelationSingle(
+            Client::class,
+            function ($query) {
+                $query
+                    ->join('projects', 'clients.id', 'client_id')
+                    ->join('orders', 'projects.id', 'project_id')
+                    ->join('tasks', 'orders.id', 'order_id');
+            },
+        );
+    }
+}
 ```
 
-Optionally, you can publish the views using
-
-```bash
-php artisan vendor:publish --tag=":package_slug-views"
+```php
+class Client extends Model {
+
+    use HasCustomRelation;
+
+    public function tasks(): CustomRelation {
+        return $this->customRelation(
+            Task::class,
+            function ($query) {
+                $query
+                    ->join('orders', 'orders.id', 'order_id')
+                    ->join('projects', 'projects.id', 'project_id')
+                    ->join('clients', 'clients.id', 'client_id');
+            },
+        );
+    }
+}
 ```
 
-## Usage
+Like regular Laravel Relations, the query builder starts from the related model.
+This results in the following join chains:  
+$task->client: ``Client->Projects->Orders->Tasks``  
+$client->tasks: ``Tasks->Orders->Projects->Client``
 
+If you prefer starting the join from the model the relation is defined on, you can use the method with the ``fromParent`` suffix:
 ```php
-$variable = new VendorName\Skeleton();
-echo $variable->echoPhrase('Hello, VendorName!');
+class Task extends Model {
+
+    use HasCustomRelation;
+
+    public function client(): CustomRelationSingle {
+        return $this->customRelationFromParentSingle(
+            Client::class,
+            function ($query) {
+                $query
+                    ->join('orders', 'orders.id', 'order_id')
+                    ->join('projects', 'projects.id', 'project_id')
+                    ->join('clients', 'clients.id', 'client_id');
+            },
+        );
+    }
+}
 ```
 
+```php
+class Client extends Model {
+
+    use HasCustomRelation;
+
+    public function tasks(): CustomRelation {
+        return $this->customRelationFromParent(
+            Task::class,
+            function ($query) {
+                $query
+                    ->join('projects', 'clients.id', 'client_id')
+                    ->join('orders', 'projects.id', 'project_id')
+                    ->join('tasks', 'orders.id', 'order_id');
+            },
+        );
+    }
+}
+```
+
+## Limitations
+Since the query might introduce a lot of joins, some methods known from Laravel Relations are not available:
+- make
+- create
+- update
+- forceCreate
+- forceDelete
+
 ## Testing
 
 ```bash
@@ -85,7 +171,7 @@ Please review [our security policy](../../security/policy) on how to report secu
 
 ## Credits
 
-- [:author_name](https://github.com/:author_username)
+- [Adrian Hawlitschek](https://github.com/53199186+ahawlitschek)
 - [All Contributors](../../contributors)
 
 ## License

composer.json

@@ -1,17 +1,17 @@
 {
-    "name": ":vendor_slug/:package_slug",
-    "description": ":package_description",
+    "name": "clickbar/laravel-custom-relations",
+    "description": "This package provides functionality for custom relations in laravel",
     "keywords": [
-        ":vendor_name",
+        "clickbar",
         "laravel",
-        ":package_slug"
+        "laravel-custom-relations"
     ],
-    "homepage": "https://github.com/:vendor_slug/:package_slug",
+    "homepage": "https://github.com/clickbar/laravel-power-relations",
     "license": "MIT",
     "authors": [
         {
-            "name": ":author_name",
-            "email": "[email protected]",
+            "name": "Adrian Hawlitschek",
+            "email": "[email protected]",
             "role": "Developer"
         }
     ],
@@ -30,24 +30,23 @@
         "pestphp/pest-plugin-laravel": "^2.0",
         "phpstan/extension-installer": "^1.1",
         "phpstan/phpstan-deprecation-rules": "^1.0",
-        "phpstan/phpstan-phpunit": "^1.0",
-        "spatie/laravel-ray": "^1.26"
+        "phpstan/phpstan-phpunit": "^1.0"
     },
     "autoload": {
         "psr-4": {
-            "VendorName\\Skeleton\\": "src/",
-            "VendorName\\Skeleton\\Database\\Factories\\": "database/factories/"
+            "Clickbar\\LaravelCustomRelations\\": "src/",
+            "Clickbar\\LaravelCustomRelations\\Database\\Factories\\": "database/factories/"
         }
     },
     "autoload-dev": {
         "psr-4": {
-            "VendorName\\Skeleton\\Tests\\": "tests/",
+            "Clickbar\\LaravelCustomRelations\\Tests\\": "tests/",
             "Workbench\\App\\": "workbench/app/"
         }
     },
     "scripts": {
         "post-autoload-dump": "@composer run prepare",
-        "clear": "@php vendor/bin/testbench package:purge-skeleton --ansi",
+        "clear": "@php vendor/bin/testbench package:purge-laravel-custom-relations --ansi",
         "prepare": "@php vendor/bin/testbench package:discover --ansi",
         "build": [
             "@composer run prepare",
@@ -61,7 +60,7 @@
         "analyse": "vendor/bin/phpstan analyse",
         "test": "vendor/bin/pest",
         "test-coverage": "vendor/bin/pest --coverage",
-        "format": "vendor/bin/pint"
+        "fix": "vendor/bin/pint"
     },
     "config": {
         "sort-packages": true,
@@ -73,11 +72,8 @@
     "extra": {
         "laravel": {
             "providers": [
-                "VendorName\\Skeleton\\SkeletonServiceProvider"
-            ],
-            "aliases": {
-                "Skeleton": "VendorName\\Skeleton\\Facades\\Skeleton"
-            }
+              "LaravelCustomRelationsServiceProvider"
+            ]
         }
     },
     "minimum-stability": "dev",

config/power-relations.php

@@ -0,0 +1,6 @@
+<?php
+
+// config for Clickbar/LaravelPowerRelations
+return [
+
+];