Merge remote-tracking branch 'origin/master'

app/Http/Controllers/PomoController.php

@@ -9,6 +9,9 @@ use Illuminate\Auth\Access\AuthorizationException;
 use Illuminate\Contracts\Foundation\Application;
 use Illuminate\Contracts\View\Factory;
 use Illuminate\Contracts\View\View;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Support\Facades\App;
 use Illuminate\Support\Facades\Auth;
 use App\Models\{
     Pomo,
@@ -21,11 +24,13 @@ use Illuminate\Http\Request;
 class PomoController extends Controller
 {
     /**
-     * Display a listing of the resource.
+     * Display a listing of Pomos of a given todo
+     * @param Request $request - Request object (Should contain todo_id if API Request)
+     * @return PomoResource|Application|Factory|View - Returns PomoResource if API, Index View if not
      */
     public function index(Request $request): PomoResource|Application|Factory|View
     {
-        if ($request->expectsJson()){
+        if ($request->expectsJson()) {
             $todo = Todo::find($request->todo_id);
             $pomos = $todo->pomo()->paginate(4);
 
@@ -36,9 +41,12 @@ class PomoController extends Controller
     }
 
     /**
-     * Show the form for creating a new resource.
+     * Show the form for creating a new Pomo
+     * @param null $todo_id - ID of Todo to create Pomo for
+     * @return Application|Factory|View - Returns view of create Pomo form
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to create Pomo
      */
-    public function create($todo_id = null)
+    public function create($todo_id = null): Application|Factory|View
     {
         $this->authorize('create', Pomo::class);
 
@@ -50,9 +58,12 @@ class PomoController extends Controller
     }
 
     /**
-     * Store a newly created resource in storage.
+     * Store a newly created Pomo in storage.
+     * @param StorePomoRequest $request - Request object containing Validated data from create Pomo form
+     * @return RedirectResponse|JsonResponse - Returns redirect to Pomo index if not API, JSON response if API
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to create Pomo
      */
-    public function store(StorePomoRequest $request)
+    public function store(StorePomoRequest $request): RedirectResponse|JsonResponse
     {
         $this->authorize('create', Pomo::class);
 
@@ -64,7 +75,7 @@ class PomoController extends Controller
         $pomo->notes = $request->safe()->notes;
         $pomo->save();
 
-        if ($request->expectsJson()){
+        if ($request->expectsJson()) {
             return response()->json([
                 'message' => 'Pomo created successfully.',
                 'data' => $pomo,
@@ -76,13 +87,17 @@ class PomoController extends Controller
     }
 
     /**
-     * Display the specified resource.
+     * Display the specified Pomo.
+     * @param Request $request - Request object
+     * @param Pomo $pomo - Pomo to be displayed
+     * @return JsonResponse|Application|Factory|View - Returns JSON response of Pomo if API, Pomo view if not
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to view the Pomo
      */
-    public function show(Request $request, Pomo $pomo)
+    public function show(Request $request, Pomo $pomo): JsonResponse|Application|Factory|View
     {
         $this->authorize('view', $pomo);
 
-        if ($request->expectsJson()){
+        if ($request->expectsJson()) {
             return response()->json([
                 'message' => 'Pomo retrieved successfully.',
                 'data' => $pomo,
@@ -94,9 +109,11 @@ class PomoController extends Controller
 
     /**
      * Show the form for editing the specified resource.
-     * @throws AuthorizationException
+     * @param Pomo $pomo - Pomo to be edited
+     * @return Application|Factory|View - Returns view of edit Pomo form
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to edit the Pomo
      */
-    public function edit(Pomo $pomo)
+    public function edit(Pomo $pomo): Application|Factory|View
     {
         $this->authorize('view', $pomo);
 
@@ -106,9 +123,13 @@ class PomoController extends Controller
     }
 
     /**
-     * Update the specified resource in storage.
+     * Update the specified Pomo in storage.
+     * @param UpdatePomoRequest $request - Request object containing Validated data from edit Pomo form
+     * @param Pomo $pomo - Pomo to be updated
+     * @return RedirectResponse|JsonResponse - Returns redirect to Pomo index if not API, JSON response if API
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to update the Pomo
      */
-    public function update(UpdatePomoRequest $request, Pomo $pomo)
+    public function update(UpdatePomoRequest $request, Pomo $pomo): RedirectResponse|JsonResponse
     {
         $this->authorize('update', $pomo);
 
@@ -118,7 +139,7 @@ class PomoController extends Controller
         $pomo->notes = $request->notes;
         $pomo->save();
 
-        if ($request->expectsJson()){
+        if ($request->expectsJson()) {
             return response()->json([
                 'message' => 'Pomo updated successfully.',
                 'data' => $pomo,
@@ -130,17 +151,20 @@ class PomoController extends Controller
     }
 
     /**
-     * Remove the specified resource from storage.
+     * Remove the specified Pomo from storage.
-     * @throws AuthorizationException
+     * @param Request $request - Request object
+     * @param Pomo $pomo - Pomo to be deleted
+     * @return RedirectResponse|JsonResponse - Returns redirect to Pomo index if not API, JSON response if API
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to delete the Pomo
      */
-    public function destroy(Request $request, Pomo $pomo)
+    public function destroy(Request $request, Pomo $pomo): RedirectResponse|JsonResponse
     {
         // Validate that the user is authorized to delete the pomo
         $this->authorize('delete', [Pomo::class, $pomo]);
 
         $pomo->delete();
 
-        if ($request->expectsJson()){
+        if ($request->expectsJson()) {
             return response()->json([
                 'message' => 'Pomo deleted successfully.',
             ], 200);

app/Http/Controllers/ProjectController.php

@@ -22,9 +22,13 @@ use Illuminate\Support\Facades\Response;
 
 class ProjectController extends Controller
 {
-    protected mixed $project_api_route_pattern = 'api/*';
     /**
      * Display Listing of all Projects.
+     * This function handles both API and non-API requests
+     * API: Returns JSON response of all projects
+     * Non-API: Returns view of all projects
+     * @param Request $request - Request object
+     * @return View|Factory|Application|JsonResponse|ProjectResource - Returns view of all projects or ProjectResource/JSON response
      * @throws AuthorizationException
      */
     public function index(Request $request): View|Factory|Application|JsonResponse|ProjectResource
@@ -65,6 +69,7 @@ class ProjectController extends Controller
 
     /**
      * Show the form for creating a new resource.
+     * @return View|\Illuminate\Foundation\Application|Factory|Application - Returns view of project create page
      */
     public function create(): View|\Illuminate\Foundation\Application|Factory|Application
     {
@@ -73,6 +78,11 @@ class ProjectController extends Controller
 
     /**
      * Store a newly created project in storage.
+     * This function handles both API and non-API requests
+     * API: Returns JSON response of project if created successfully and 201 status code (created)
+     * Non-API: Redirects to project index page if project created successfully
+     * @param StoreProjectRequest $request - Request object with validation rules for project creation
+     * @return RedirectResponse|JsonResponse - Redirects to project index page or returns JSON response
      */
     public function store(StoreProjectRequest $request): RedirectResponse|JsonResponse
     {
@@ -101,7 +111,14 @@ class ProjectController extends Controller
     }
 
     /**
-     * Display the specified resource.
+     * Display the specified project.
+     * This function handles both API and non-API requests
+     * API: Returns JSON response of project
+     * Non-API: Displays project view of project
+     * @param Request $request - Request object
+     * @param $project_id - Project ID to be displayed (passed from route)
+     * @return RedirectResponse|JsonResponse -
+     * Redirects to project index page or returns JSON response
      * @throws AuthorizationException
      */
     public function show(Request $request, $project_id): RedirectResponse|JsonResponse
@@ -136,6 +153,8 @@ class ProjectController extends Controller
 
     /**
      * Show the form for editing the specified Project.
+     * @param Project $project - Project object to be edited (passed from route)
+     * @return View|\Illuminate\Foundation\Application|Factory|Application - Returns view of project edit page
      * @throws AuthorizationException
      */
     public function edit(Project $project): View|\Illuminate\Foundation\Application|Factory|Application
@@ -148,10 +167,14 @@ class ProjectController extends Controller
 
     /**
      * Update the specified Project in storage.
+     * This function handles completion toggle and/or updating of other fields
+     * @param UpdateProjectRequest $request - Request object with validation rules
+     * @param $project_id - Project ID to be updated
+     * @return RedirectResponse|JsonResponse - Redirects to previous page or returns JSON response
+     * @throws AuthorizationException
      */
     public function update(UpdateProjectRequest $request, $project_id): RedirectResponse|JsonResponse
     {
-
         $data = $request->validatedWithCompletedAt();
 
         // API Call
@@ -198,6 +221,12 @@ class ProjectController extends Controller
 
     /**
      * Remove the specified Project from storage.
+     * This function handles both API and non-API requests
+     * API: Returns JSON response of project if found and deleted
+     * Non-API: Redirects to project index page if project found and deleted
+     * @param $project_id - Project ID to be deleted (passed from route)
+     * @param Request $request - Request object
+     * @return RedirectResponse|JsonResponse - Redirects to project index page or returns JSON response
      * @throws AuthorizationException
      */
     public function destroy($project_id, Request $request): RedirectResponse|JsonResponse

app/Http/Controllers/ProjectTodoController.php

@@ -8,6 +8,7 @@ use App\Http\Resources\TodoResource;
 use App\Models\Project;
 use App\Models\Todo;
 use App\Models\User;
+use Illuminate\Auth\Access\AuthorizationException;
 use Illuminate\Contracts\View\Factory;
 use Illuminate\Contracts\View\View;
 use Illuminate\Foundation\Application;
@@ -20,15 +21,20 @@ use Illuminate\Support\Facades\Gate;
 
 class ProjectTodoController extends Controller
 {
-    private string $timezone = 'Asia/Singapore';
-
     /**
      * Display a listing of all Todos for a Project.
+     * This function handles both API and non-API requests
+     * API: Returns JSON response of all Todos for a Project paginated
+     * Non-API: Returns view of all Todos for a Project
+     * @param Request $request - Request object
+     * @param $project_id - Project ID of the desired Project
+     * @return View|Factory|Application|RedirectResponse|TodoResource|JsonResponse - Returns view of all Todos for a Project or TodoResource/JSON response
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to view the Project
      */
     public function index(Request $request, $project_id): Factory|Application|View|RedirectResponse|TodoResource|JsonResponse
     {
         $user = Auth::user();
-        $project = $user->projects()->find($project_id);
+        $project = $user->projects->find($project_id);
 
         if (!$project) {
             if ($request->expectsJson()) {
@@ -63,7 +69,9 @@ class ProjectTodoController extends Controller
     }
 
     /**
-     * Show the form for creating a new resource.
+     * Show the form for creating a new Todo for the particular Project.
+     * @param $project_id - Project ID of the desired Project
+     * @return View|Factory|Application - Returns view of create Todo form
      */
     public function create($project_id): Factory|View|Application
     {
@@ -75,6 +83,10 @@ class ProjectTodoController extends Controller
 
     /**
      * Store a newly created Todo in storage.
+     * @param $project_id - Project ID of the desired Project to store the Todo in
+     * @param StoreTodoRequest $request - StoreTodoRequest object with validation rules for Todo creation
+     * @return RedirectResponse|JsonResponse - Redirects to Todo index page or returns JSON response
+     * @throws AuthorizationException
      */
     public function store($project_id, StoreTodoRequest $request): RedirectResponse|JsonResponse
     {
@@ -100,9 +112,14 @@ class ProjectTodoController extends Controller
 
 
     /**
-     * Display the specified resource.
+     * Display the specified Todo if API request.
+     * Redirects to Todo index page if non-API request. (Shows all Todos for a Project)
+     * @param Request $request - Request object (Should contain todo_id if API request)
+     * @param $project_id - Project ID of the desired Project
+     * @return JsonResponse|RedirectResponse|View - Returns JSON response of Todo if API request or redirects to Todo index page
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to view the Todo
      */
-    public function show(Request $request, $project_id)
+    public function show(Request $request, $project_id): JsonResponse|RedirectResponse|View
     {
         if ($request->expectsJson()) {
             $user = Auth::user();
@@ -118,19 +135,16 @@ class ProjectTodoController extends Controller
         }
 
         return redirect()->route('project.todo.index', $project_id);
-//        $user = Auth::user();
-//        $projects = $user->projects;
-//        $project = $projects->find($project_id);
-//
-//        $this->authorize('view', [Todo::class, $project, $project->todos->find($request->todo_id)]);
-//
-//        return view('todo.show', compact('project', 'todo'));
     }
 
     /**
-     * Show the form for editing the specified resource.
+     * Show the form for editing the specified Todo.
+     * @param $project_id - Project ID of todo to be edited
+     * @param Todo $todo - Todo to be edited
+     * @return View|Factory|Application - Returns view of edit Todo form
+     * @throws AuthorizationException - Throws AuthorizationException if user is not authorized to edit the Todo
      */
-    public function edit($project_id, Todo $todo)
+    public function edit($project_id, Todo $todo): Factory|View|Application
     {
         $projects = auth()->user()->projects;
         $project = $projects->find($project_id);
@@ -141,11 +155,13 @@ class ProjectTodoController extends Controller
 
     /**
      * Update Todo in storage based on the given project
+     * @param $project_id - Project ID of the desired Project
+     * @param UpdateTodoRequest $request - UpdateTodoRequest object with validation rules for Todo update
+     * @param Todo $todo - Todo to be updated
+     * @return RedirectResponse|JsonResponse - Redirects to Todo index page or returns JSON response
      */
-    public function update($project_id, UpdateTodoRequest $request, Todo $todo)
+    public function update($project_id, UpdateTodoRequest $request, Todo $todo): RedirectResponse|JsonResponse
     {
-//        $project = auth()->user()->projects->find($project_id);
-
         if (Gate::denies('update', $todo)) {
             return back()->with('error', 'You are not authorized to update this todo');
         }
@@ -177,7 +193,11 @@ class ProjectTodoController extends Controller
 
 
     /**
-     * Remove the specified resource from storage.
+     * Remove the specified Todo from storage.
+     * @param $project_id - Project ID of the desired Project
+     * @param Request $request - Request object
+     * @param Todo $todo - Todo to be deleted
+     * @return RedirectResponse|JsonResponse - Redirects to Todo index page or returns JSON response
      */
     public function destroy($project_id, Request $request, Todo $todo): RedirectResponse|JsonResponse
     {