<?php

namespace Illuminate\Database\Eloquent\Relations;

use Illuminate\Support\Str;
use InvalidArgumentException;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\ModelNotFoundException;

/**
* @template TRelatedModel of Model
* @template-extends Relation<TRelatedModel>
* @mixin \Illuminate\Database\Eloquent\Builder<TRelatedModel>
*/
class BelongsToMany extends Relation
{
    use Concerns\InteractsWithPivotTable;

    /**
     * Create a new belongs to many relationship instance.
     *
     * @param  \Illuminate\Database\Eloquent\Builder  $query
     * @param  \Illuminate\Database\Eloquent\Model  $parent
     * @param  string  $table
     * @param  string  $foreignPivotKey
     * @param  string  $relatedPivotKey
     * @param  string  $parentKey
     * @param  string  $relatedKey
     * @param  string  $relationName
     * @return void
     */
    public function __construct(Builder $query, Model $parent, $table, $foreignPivotKey,
                                $relatedPivotKey, $parentKey, $relatedKey, $relationName = null)
    {
        $this->parentKey = $parentKey;
        $this->relatedKey = $relatedKey;
        $this->relationName = $relationName;
        $this->relatedPivotKey = $relatedPivotKey;
        $this->foreignPivotKey = $foreignPivotKey;
        $this->table = $this->resolveTableName($table);

        parent::__construct($query, $parent);
    }

    /**
     * @template T
     * @psalm-param T $id
     * @param  mixed  $id
     * @param  array  $columns
     * @return \Illuminate\Support\Collection|\Illuminate\Database\Eloquent\Model
     * @psalm-return (T is array ? \Illuminate\Support\Collection<TRelatedModel>|TRelatedModel
     */
    public function findOrNew($id, $columns = ['*']) { }

    /**
     * @param  array  $attributes
     * @return \Illuminate\Database\Eloquent\Model
     * @psalm-return TRelatedModel
     */
    public function firstOrNew(array $attributes) { }

    /**
     * @param  array  $attributes
     * @param  array  $joining
     * @param  bool   $touch
     * @return \Illuminate\Database\Eloquent\Model
     * @psalm-return TRelatedModel
     */
    public function firstOrCreate(array $attributes, array $joining = [], $touch = true) { }

    /**
     * @param  array  $attributes
     * @param  array  $values
     * @param  array  $joining
     * @param  bool   $touch
     * @return \Illuminate\Database\Eloquent\Model
     * @psalm-return TRelatedModel
     */
    public function updateOrCreate(array $attributes, array $values = [], array $joining = [], $touch = true) { }

    /**
     * @template T
     * @psalm-param T $id
     * @param  mixed  $id
     * @param  array  $columns
     * @return \Illuminate\Database\Eloquent\Model|\Illuminate\Database\Eloquent\Collection|null
     * @psalm-return (T is array ? \Illuminate\Database\Eloquent\Collection<TRelatedModel>|null : TRelatedModel|null)
     */
    public function find($id, $columns = ['*']) { }

    /**
     * @param  mixed  $ids
     * @param  array  $columns
     * @return \Illuminate\Database\Eloquent\Collection
     * @psalm-return \Illuminate\Database\Eloquent\Collection<TRelatedModel>
     */
    public function findMany($ids, $columns = ['*']) { }

    /**
     * @param  mixed  $id
     * @param  array  $columns
     * @return \Illuminate\Database\Eloquent\Model|\Illuminate\Database\Eloquent\Collection
     * @psalm-return TRelatedModel
     *
     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
     */
    public function findOrFail($id, $columns = ['*']) { }

    /**
     * @param  array   $columns
     * @return mixed
     * @psalm-return TRelatedModel|null
     */
    public function first($columns = ['*']) { }

    /**
     * Execute the query and get the first result or throw an exception.
     *
     * @param  array  $columns
     * @return \Illuminate\Database\Eloquent\Model|static
     * @psalm-return TRelatedModel
     *
     * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
     */
    public function firstOrFail($columns = ['*']) { }

    /**
     * @param  array  $columns
     * @return \Illuminate\Database\Eloquent\Collection
     * @psalm-return \Illuminate\Database\Eloquent\Collection<TRelatedModel>
     */
    public function get($columns = ['*']) { }

    /**
     * @param  array  $attributes
     * @param  array  $joining
     * @param  bool   $touch
     * @return \Illuminate\Database\Eloquent\Model
     * @psalm-return TRelatedModel
     */
    public function create(array $attributes = [], array $joining = [], $touch = true) { }

    /**
     * @param  array  $records
     * @param  array  $joinings
     * @return array
     * @psalm-return array<TRelatedModel>
     */
    public function createMany(array $records, array $joinings = []) { }
}