Try to increase quality of the codebase

src/API/AvailabilityRoute.php

@@ -3,23 +3,21 @@
 
 namespace CommonsBooking\API;
 
-use CommonsBooking\Helper\Wordpress;
 use CommonsBooking\Model\Calendar;
 use CommonsBooking\Model\Day;
-use CommonsBooking\Model\Timeframe;
-use CommonsBooking\Model\Week;
 use CommonsBooking\Repository\Item;
-use DateTime;
-use DateTimeZone;
 use Exception;
 use stdClass;
 use WP_Error;
+use WP_REST_Request;
 use WP_REST_Response;
 
 /**
  * Endpoint exposes item availability
  *
- * @See Calendar for computing item availability
+ * @see Calendar for computing item availability.
+ *
+ * @see JSON-schema-Specification {@see https://github.com/wielebenwir/commons-api/blob/master/commons-api.availability.schema.json}
  */
 class AvailabilityRoute extends BaseRoute {
 
@@ -40,9 +38,7 @@ class AvailabilityRoute extends BaseRoute {
 	/**
 	 * This retrieves bookable timeframes and the different items assigned, with their respective availability.
 	 *
-	 * @param bool $id The id of a \CommonsBooking\Wordpress\CustomPostType\Item::post_type post to search for
-	 * @param null $startTime The start date of the calendar to get the data for
-	 * @param null $endTime The end date of the calendar to get the data for
+	 * @param bool $id The id of a {@see \CommonsBooking\Wordpress\CustomPostType\Item::post_type} post to search for
 	 *
 	 * @return array
 	 * @throws Exception
@@ -60,6 +56,10 @@ public function getItemData( $id = false ): array {
 
 	/**
 	 * Get one item from the collection
+	 *
+	 * @param $request WP_REST_Request
+	 *
+	 * @return WP_REST_Response|WP_Error
 	 */
 	public function get_item( $request ) {
 		//get parameters from request
@@ -72,7 +72,9 @@ public function get_item( $request ) {
 			if ( count( $data->availability ) ) {
 				return new WP_REST_Response( $data, 200 );
 			} else {
-
+				// This was missing in previous versions. According to the availability spec, we can return a list with no items
+				// TODO this part and the enclosing if-clause can be removed in future version, if no problems arose ...
+				return new WP_REST_Response( $data, 200 );
 			}
 		} catch (Exception $e) {
 			return new WP_Error( 'code', $e->getMessage() );
@@ -83,7 +85,7 @@ public function get_item( $request ) {
 	/**
 	 * Get a collection of items
 	 *
-	 * @param $request Full data about the request.
+	 * @param $request WP_REST_Request full data about the request.
 	 *
 	 * @return WP_REST_Response
 	 */

src/CB/CB1UserFields.php

@@ -10,6 +10,31 @@
 
 class CB1UserFields {
 
+	/**
+	 * @var false|mixed
+	 */
+	private mixed $termsservices_url;
+	/**
+	 * @var array|string[]
+	 */
+	private array $registration_fields;
+	/**
+	 * @var array|array[]
+	 */
+	private array $extra_profile_fields;
+	/**
+	 * @var array|string[]
+	 */
+	private array $registration_fields_required;
+	/**
+	 * @var array|array[]
+	 */
+	private array $user_fields;
+	/**
+	 * @var array|mixed
+	 */
+	private mixed $user_vars;
+
 	public function __construct() {
 
 		// Registration: Form fields

src/Exception/TimeframeInvalidException.php

@@ -6,7 +6,7 @@
 
 class TimeframeInvalidException extends \Exception {
 
-	public function __construct( $message = "", $code = 0, Throwable $previous = null ) {
+	public function __construct( $message = "", $code = 0, \Throwable $previous = null ) {
 		//get immediate caller
 		if ( debug_backtrace()[1]['class'] == Booking::class ) {
 			$message .= " " . __( "Booking is saved as draft.", 'commonsbooking' );

src/Map/BaseShortcode.php

@@ -9,6 +9,8 @@
  */
 abstract class BaseShortcode {
 
+	final public function __construct() { }
+
 	/**
 	 * The shortcode handler - load all the needed assets and render the map container
 	 *

src/Model/CustomPost.php

@@ -11,7 +11,15 @@
  * Pseudo extends WP_Post class.
  *
  * All the public methods are available as template tags.
+ * * In using magic methods you can retrieve data from model objects, when the model object class derive from this class.
+ * * All the public methods are available as template tags.
+ *
  * @package CommonsBooking\Model
+ *
+ * @property int $post_author identifier of the WordPress user.
+ * @property int $post_status describes whether the post is published.
+ * @property int $ID of the WordPress post.
+ * @property string $post_title
  */
 class CustomPost {
 	/**
@@ -27,17 +35,17 @@ class CustomPost {
 	/**
 	 * CustomPost constructor.
 	 *
-	 * @param int|WP_Post $post
+	 * @param int|WP_Post $post uses either int as id reference or the post object
 	 *
-	 * @throws Exception
+	 * @throws Exception when $post param does not reference a valid post object
 	 */
 	public function __construct( $post ) {
 		if ( $post instanceof WP_Post ) {
 			$this->post = $post;
 		} elseif ( is_int( $post ) ) {
 			$this->post = get_post( $post );
 		} else {
-			throw new Exception( "Invalid post param. Needed WP_Post or ID (int)" );
+			throw new Exception( 'Invalid post param. Needed WP_Post or ID (int)' );
 		}
 	}
 
@@ -87,6 +95,15 @@ public function __get( $name ) {
 		}
 	}
 
+	/**
+	 * Enables that we can call methods of \CustomPost as template tags.
+	 *
+	 * @param string $name of the member function
+	 * @param array  $arguments given to the template tag.
+	 *
+	 * @return array|mixed|void
+	 * @throws \ReflectionException if called template tag is not a registered method
+	 */
 	public function __call( $name, $arguments ) {
 		if ( method_exists( $this->post, $name ) ) {
 			$reflectionMethod = new ReflectionMethod( $this->post, $name );

src/Model/Timeframe.php

@@ -222,7 +222,7 @@ public function getLatestPossibleBookingDateTimestamp() {
 		$calculationBase = time();
 
 		// if meta-value not set we define a default value far in the future so that we count all possibly relevant timeframes
-		$advanceBookingDays = $this->getMeta( TimeFrame::META_TIMEFRAME_ADVANCE_BOOKING_DAYS ) ?: 365;
+		$advanceBookingDays = $this->getMeta( Timeframe::META_TIMEFRAME_ADVANCE_BOOKING_DAYS ) ?: 365;
 
 		// we subtract one day to reflect the current day in calculation
 		$advanceBookingDays --;

src/Plugin.php

@@ -29,6 +29,10 @@
 use CommonsBooking\Wordpress\Options\OptionsTab;
 use CommonsBooking\Wordpress\PostStatus\PostStatus;
 
+/**
+ * @since 2.10 removed saveOptionsActions, the transient commonsbooking_options_saved which is used in
+ *             Plugin::admin_init is set in OptionsTab class
+ */
 class Plugin {
 
 	use Cache;
@@ -513,15 +517,6 @@ public static function maybeEnableCB1UserFields() {
 		}
 	}
 
-	/**
-	 * run actions after plugin options are saved
-	 * TODOD: @markus-mw I think this function is deprecated now. Would you please check this? It is only referenced by an inactive hook
-	 */
-	public static function saveOptionsActions() {
-		// Run actions after options update
-		set_transient( 'commonsbooking_options_saved', 1 );
-	}
-
 	/**
 	 * Register Admin-Options
 	 */

src/Repository/BookingCodes.php

@@ -129,14 +129,16 @@ public static function getCodes( int $timeframeId, int $startDate = null, int $e
 
 	/**
 	 * Filter an array of BookingCode|s such that it contains only one BookingCode per date.
+	 * Works by reference on the variable.
+	 *
 	 * Function is only needed when new cb version handles database entries created by old cb version.
 	 * The filtering can be omitted in future cb versions when backward compatibility with old cb is dropped.
 	 *
-	 * @param $bookingCodes[] array of BookingCode|s. It is assumed that they all have the same itemId.
+	 * @param array &$bookingCodes reference of array of BookingCode|s. It is assumed that they all have the same itemId.
 	 * @param int $preferredTimeframeId timeframeId to prefer when filtering
 	 * @param int $preferredLocationId locationId to prefer when filtering
 	 *
-	 * @return $bookingCodes[] array of BookingCode|s (only one code per day)
+	 * @return void works by reference on param $bookingCodes
 	 */
 	private static function backwardCompatibilityFilter(&$bookingCodes, $preferredTimeframeId, $preferredLocationId) {
 		$filteredCodes = [];

src/Repository/CB1.php

@@ -243,6 +243,8 @@ public static function getCB2PostIdByCB1Id( $id ): ?int {
 		if ( $result && count( $result ) > 0 ) {
 			return $result[0]->cb2_id;
 		}
+
+		return null;
 	}
 
 	/**

src/Service/BookingRule.php

@@ -697,7 +697,8 @@ private static function checkBookingRangeForDays( DateTime $startOfRange, DateTi
 	 * @param $appliedTerms
 	 * @param int $allowedTotalBookings
 	 *
-	 * @return void
+	 * @return Booking[]|null
+	 * @throws Exception
 	 */
 	private static function checkBookingAmount( DateTime $startOfRange, DateTime $endOfRange, Booking $booking, $appliedTerms, int $allowedTotalBookings ) {
 		$countedPostTypes = [ 'confirmed' ];

src/Service/BookingRuleApplied.php

@@ -286,7 +286,7 @@ public static function init( bool $ignoreErrors = false ):array{
 				}
 				try {
 					$bookingRule->setAppliedParams(
-						$ruleParams ?? [],
+						$ruleParams,
 						$selectParam ?? null
 					);
 				} catch ( BookingRuleException $e ) {

src/Service/TimeframeExport.php

@@ -186,6 +186,19 @@ public static function ajaxExportCsv() {
 		}
 	}
 
+	/**
+	 * Exports a file to the given directory path.
+	 * This functions wraps the actual logic of {@see __construct()}, {@see getExportData} and {@see getCsv}.
+	 *
+	 * Note: At the moment this is not a helper to be used outside its context.
+	 * It's heavily coupled to different values set via {@see Settings} and should therefore not be used outside of it's WordPress context.
+	 *
+	 * @param string $exportPath writable directory.
+	 *
+	 * @return void
+	 * @throws CacheException From cache layer.
+	 * @throws InvalidArgumentException From cache layer.
+	 */
 	public static function cronExport( $exportPath ) {
 		$timerange                = Settings::getOption( 'commonsbooking_options_export', 'export-timerange' );
 		$start                    = date( 'd.m.Y' );
@@ -201,16 +214,17 @@ public static function cronExport( $exportPath ) {
 		} else {
 			$type = 0;
 		}
-		$exportObject = new self(
-			$type,
-			$start,
-			$end,
-			$configuredLocationFields ? self::convertInputFields( $configuredLocationFields ) : null,
-			$configuredItemFields ? self::convertInputFields( $configuredItemFields ) : null,
-			$configuredUserFields ? self::convertInputFields( $configuredUserFields ) : null,
-		);
-		$exportObject->setCron();
+
 		try {
+			$exportObject = new self(
+				$type,
+				$start,
+				$end,
+				$configuredLocationFields ? self::convertInputFields( $configuredLocationFields ) : null,
+				$configuredItemFields ? self::convertInputFields( $configuredItemFields ) : null,
+				$configuredUserFields ? self::convertInputFields( $configuredUserFields ) : null,
+			);
+			$exportObject->setCron();
 			$exportObject->getExportData();
 			$exportObject->getCSV( $exportPath . $exportObject->exportFilename );
 		} catch ( ExportException $e ) {

src/Wordpress/CustomPostType/Booking.php

@@ -670,6 +670,11 @@ public function setCustomColumnsData( $column, $post_id ) {
 		}
     }
 
+	/**
+	 * @param \WP_Query $query
+	 *
+	 * @return void
+	 */
 	public function setCustomColumnSortOrder( \WP_Query $query ) {
 		if (! parent::setCustomColumnSortOrder( $query ) ) {
 			return;

src/Wordpress/CustomPostType/CustomPostType.php

@@ -370,13 +370,15 @@ public static function getModel( $post ) {
 	}
 
 	/**
-	 * This is called by the inheritances of the customPosts, it will just check if we
-	 * are processing one of our CPTs.
+	 * Checks if we query is processing one of our CPTs.
+	 *
+	 * This is called by the inheritances of the customPosts.
+	 *
 	 * @param \WP_Query $query
 	 *
-	 * @return void
+	 * @return bool true if query is about our CPTs, false otherwise
 	 */
-	public function setCustomColumnSortOrder(\WP_Query $query) {
+	public function setCustomColumnSortOrder( \WP_Query $query ) {
 		if ( ! is_admin() || ! $query->is_main_query() || $query->get( 'post_type' ) !== static::$postType ) {
 			return false;
 		}

src/Wordpress/CustomPostType/Item.php

@@ -62,9 +62,9 @@ public function savePost($post_id, \WP_Post $post) {
 	/**
 	 * Filters admin list by type (e.g. bookable, repair etc. )
 	 *
-	 * @param  (wp_query object) $query
+	 * @param \WP_Query $query for admin list objects
 	 *
-	 * @return Void
+	 * @return void
 	 */
 	public static function filterAdminList( $query ) {
 		global $pagenow;

src/Wordpress/CustomPostType/Location.php

@@ -61,9 +61,9 @@ public static function termChange($term_id, $tt_id, $taxonomy) {
 	/**
 	 * Filters admin list by type (e.g. bookable, repair etc. )
 	 *
-	 * @param  (wp_query object) $query
+	 * @param \WP_Query $query for admin list objects
 	 *
-	 * @return Void
+	 * @return void
 	 */
 	public static function filterAdminList( $query ) {
 		global $pagenow;
@@ -435,6 +435,7 @@ public function registerMetabox() {
 		}
 
 		// we store registered metaboxes to options table to be able to retrieve it in export function
+		$metabox_fields = [];
 		foreach ($cmb->meta_box['fields'] as $metabox_field) {
 			$metabox_fields[$metabox_field['id']] = $metabox_field['name'];
 		}

src/Wordpress/CustomPostType/Map.php

@@ -8,6 +8,7 @@
 use CommonsBooking\Map\MapAdmin;
 use CommonsBooking\Map\MapSettings;
 use CommonsBooking\Map\MapShortcode;
+use CommonsBooking\Repository\CB1;
 use CommonsBooking\Repository\Item;
 use CommonsBooking\Repository\Timeframe;
 use Exception;
@@ -51,8 +52,7 @@ public static function getView() {
 	 **/
 	public static function replace_map_link_target() {
 		global $post;
-		$cb_item = 'cb_items';
-		if ( is_object( $post ) && $post->post_type == $cb_item ) {
+		if ( is_object( $post ) && $post->post_type == CB1::$ITEM_TYPE_ID ) {
 			//get timeframes of item
 			$cb_data    = new CB_Data();
 			$date_start = date( 'Y-m-d' ); // current date
@@ -81,6 +81,9 @@ public static function replace_map_link_target() {
 	 * load all timeframes from db (that end in the future and it's item's status is 'publish')
 	 **/
 	public static function get_timeframes() {
+
+		$result = [];
+
 		$timeframes = Timeframe::getBookableForCurrentUser(
 			[],
 			[],