1	<?php
2
3	namespace App\Http\Repositories\interfaces;
4
5	use App\Http\Models\PlanFeature;
6	use Illuminate\Support\Collection;
7
8	/**
9	* Interface for plan feature (pivot) data access operations.
10	*
11	* This repository abstracts plan-feature relationship database queries,
12	* providing methods to manage feature assignments for plans.
13	*/
14	interface IPlanFeatureRepository
15	{
16	/**
17	* Get all plan features for a specific plan.
18	*
19	* @param  string  $planId  The plan ID
20	* @return Collection<int, PlanFeature> Collection of plan features
21	*/
22	public function getByPlanId(string $planId): Collection;
23
24	/**
25	* Get all plan features for a specific plan with features loaded.
26	*
27	* @param  string  $planId  The plan ID
28	* @return Collection<int, PlanFeature> Collection of plan features with feature relation
29	*/
30	public function getByPlanIdWithFeatures(string $planId): Collection;
31
32	/**
33	* Find a specific plan feature by plan and feature ID.
34	*
35	* @param  string  $planId  The plan ID
36	* @param  string  $featureId  The feature ID
37	* @return PlanFeature|null The plan feature or null if not found
38	*/
39	public function findByPlanAndFeature(string $planId, string $featureId): ?PlanFeature;
40
41	/**
42	* Assign a feature to a plan with a specific value.
43	*
44	* @param  string  $planId  The plan ID
45	* @param  string  $featureId  The feature ID
46	* @param  mixed  $value  The value for this feature on this plan
47	* @param  bool  $isEnabled  Whether the feature is enabled (default: true)
48	* @return PlanFeature The created or updated plan feature
49	*/
50	public function assignFeature(string $planId, string $featureId, mixed $value, bool $isEnabled = true): PlanFeature;
51
52	/**
53	* Sync features for a plan (replaces all existing feature assignments).
54	*
55	* @param  string  $planId  The plan ID
56	* @param  array<array{feature_id: string, value: mixed, is_enabled?: bool}>  $features  Array of feature assignments
57	* @return Collection<int, PlanFeature> Collection of synced plan features
58	*/
59	public function syncFeatures(string $planId, array $features): Collection;
60
61	/**
62	* Remove a feature from a plan.
63	*
64	* @param  string  $planId  The plan ID
65	* @param  string  $featureId  The feature ID
66	* @return bool True if removed successfully
67	*/
68	public function removeFeature(string $planId, string $featureId): bool;
69
70	/**
71	* Remove all features from a plan.
72	*
73	* @param  string  $planId  The plan ID
74	* @return int Number of features removed
75	*/
76	public function removeAllFeaturesFromPlan(string $planId): int;
77
78	/**
79	* Get the value for a specific feature on a plan.
80	*
81	* @param  string  $planId  The plan ID
82	* @param  string  $featureKey  The feature key
83	* @return mixed The feature value or null if not found
84	*/
85	public function getFeatureValue(string $planId, string $featureKey): mixed;
86	}