Clean up and fix most phpcs issues in concert.php

1 files changed, 96 insertions, 11 deletions

diff --git a/includes/concert.php b/includes/concert.php
index a225a6e..8aec96a 100644
--- a/includes/concert.php
+++ b/includes/concert.php
@@ -8,6 +8,7 @@
 require_once __DIR__ . '/venue.php';
 
 if ( ! class_exists( 'GiglogAdmin_DuplicateConcertException' ) ) {
+    // phpcs:ignore Squiz.Commenting.ClassComment.Missing
     class GiglogAdmin_DuplicateConcertException extends Exception {
 
     }
@@ -16,8 +17,12 @@ if ( ! class_exists( 'GiglogAdmin_DuplicateConcertException' ) ) {
 if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
     require_once __DIR__ . '/venue.php';
 
+    /**
+     * Class to hold all information about a given concert.
+     */
     class GiglogAdmin_Concert {
 
+        // phpcs:disable Squiz.Commenting.VariableComment.Missing
         private ?int $id;
         private ?string $cname;
         private ?GiglogAdmin_Venue $venue;
@@ -28,6 +33,7 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
         private array $roles;
         private ?DateTimeImmutable $created;
         private ?DateTimeImmutable $updated;
+        // phpcs:enable
 
         public const STATUS_NONE = 0;
         public const STATUS_ACCRED_REQ = 1;
@@ -37,11 +43,14 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
         public const STATUS_REJECTED = 5;
 
 
-        /*
+        /**
          * Constructs a new concert object from an array of attributes.
+         *
          * The attributes are expected to be named as in the database,
          * so this constructor can be used to construct the object
          * directly from the database row.
+         *
+         * @param object $attrs an object or array with the attributes.
          */
         public function __construct( object $attrs ) {
             $this->id = isset( $attrs->id ) ? $attrs->id : null;
@@ -74,13 +83,24 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
         /**
          * Return the concert with the given id.
          *
-         * @param int $id
+         * @param int $id Database id of the concert to fetch.
          * @return null|self
          */
-        static function get( int $id ) : ?self {
+        public static function get( int $id ) : ?self {
             return self::find_concerts( array( 'id' => $id ) )[0];
         }
 
+        /**
+         * Create a new concert object.
+         *
+         * @param string $name  The concert description.
+         * @param int    $venue_id The id of the venue where the concert will be held.
+         * @param string $date  The date of the concert.
+         * @param string $ticketlink    URL where tickets can be bough.
+         * @param string $eventlink     URL for more information about concert.
+         *
+         * @throws GiglogAdmin_DuplicateConcertException If concert is a duplicate.
+         */
         public static function create( string $name, int $venue_id, string $date, string $ticketlink, string $eventlink ): ?self {
             $gigs = self::find_concerts(
                 array(
@@ -112,6 +132,11 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
         }
 
 
+        /**
+         * Update a concert with new content and save to database.
+         *
+         * @param object $attrs Object or array of changed attributes.
+         */
         public function update( object $attrs ) : bool {
             $need_update = false;
 
@@ -157,6 +182,12 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
             return $need_update;
         }
 
+        /**
+         * Build a query with given filters.
+         *
+         * @param array $filter     Filters to include in the query.
+         * @param bool  $count      Only return count of result if true.
+         */
         private static function _build_query( array $filter = array(), bool $count = false ) : string {
             global $wpdb;
 
@@ -191,16 +222,16 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
                     case 'month':
                     case 'venue':
                     case 'city':
-                        array_push( $where, $wpdb->prepare( $keymap[ $key ] . '=%s', $value ) );
+                        array_push( $where, $wpdb->prepare( '%s=%s', $keymap[ $key ], $value ) );
                         break;
 
                     case 'id':
                     case 'venue_id':
-                        array_push( $where, $wpdb->prepare( $keymap[ $key ] . '=%d', $value ) );
+                        array_push( $where, $wpdb->prepare( '%s=%d', $keymap[ $key ], $value ) );
                         break;
 
                     case 'currentuser':
-                        array_push( $where, $wpdb->prepare( $keymap[ $key ] . ' like "%%%s%%"', $value ) );
+                        array_push( $where, $wpdb->prepare( '%s like %s', $keymap[ $key ], esc_like( $value ) ) );
                         break;
 
                     case 'offset':
@@ -234,13 +265,15 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
          *   - 'venue_id' => int : only include concerts at the given venue
          *   - 'city' => string  : only include concerts in the given city
          *
-         * @param array<string, mixed> $filter
+         * @param array<string, mixed> $filter Filter to use for the query.
          * @return array<GiglogAdmin_Concert>
          */
         public static function find_concerts( array $filter = array() ) : array {
             global $wpdb;
 
             $query = self::_build_query( $filter, false );
+
+            // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
             $results = $wpdb->get_results( $query );
 
             return array_map(
@@ -254,18 +287,23 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
         /**
          * Return the number of objects matching the given filter.
          *
-         * @param array<string, mixed> $filter
+         * @param array<string, mixed> $filter The filter to use for the query.
          * @return int
          */
         public static function count( array $filter = array() ) : int {
             global $wpdb;
 
             $query = self::_build_query( $filter, true );
+
+            // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared
             $count = $wpdb->get_var( $query );
 
             return $count ? $count : 0;
         }
 
+        /**
+         * Save concert to database.
+         */
         public function save() : void {
             global $wpdb;
 
@@ -279,43 +317,73 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
                 'wpgconcert_roles' => wp_json_encode( $this->roles ),
             );
 
-            if ( $this->id !== null ) {
+            if ( null !== $this->id ) {
                 $res = $wpdb->update( $wpdb->prefix . 'giglogadmin_concerts', $columns, array( 'id' => $this->id ) );
             } else {
                 $res = $wpdb->insert( $wpdb->prefix . 'giglogadmin_concerts', $columns );
             }
 
-            if ( $res === false ) {
+            if ( false === $res ) {
                 $wpdb->print_error( __METHOD__ );
-            } elseif ( $this->id === null ) {
+            } elseif ( null === $this->id ) {
                 $this->id = $wpdb->insert_id;
             }
         }
 
+        /**
+         * Return database id for concert.
+         */
         public function id() {
              return $this->id;
         }
 
+        /**
+         * Return the concert "name".
+         */
         public function cname() {
              return $this->cname;
         }
+
+        /**
+         * Return the concert venue.
+         */
         public function venue() {
              return $this->venue;
         }
+
+        /**
+         * Return the date of the concert.
+         */
         public function cdate() {
              return $this->cdate;
         }
+
+        /**
+         * Return the ticket url for the concert.
+         */
         public function tickets() {
              return $this->tickets;
         }
+
+        /**
+         * Return the event link for the concert.
+         */
         public function eventlink() {
              return $this->eventlink;
         }
 
+        /**
+         * Return the status of the concert.
+         */
         public function status() {
              return $this->status;
         }
 
+        /**
+         * Set the status of the concert.
+         *
+         * @param int $new_status   The new status for the concert.
+         */
         public function set_status( int $new_status ) {
              $this->status = $new_status;
         }
@@ -329,18 +397,35 @@ if ( ! class_exists( 'GiglogAdmin_Concert' ) ) {
             return $this->roles;
         }
 
+        /**
+         * Assign a role for the concert to the given user.
+         *
+         * @param string $role  The role to assign.
+         * @param string $username  The user to assign the role to.
+         */
         public function assign_role( string $role, string $username ) : void {
             $this->roles[ $role ] = $username;
         }
 
+        /**
+         * Unassign any roles for this concert for the given user.
+         *
+         * @param string $username  The user to remove from the roles.
+         */
         public function remove_user_from_roles( string $username ) : void {
             $this->roles = array_filter( $this->roles, fn( $u) => $u != $username );
         }
 
+        /**
+         * Return creation time of the concert object.
+         */
         public function created() : DateTimeImmutable {
             return $this->created;
         }
 
+        /**
+         * Return time of last update to this concert object.
+         */
         public function updated() : DateTimeImmutable {
             return $this->updated;
         }