Increase test and linting coverage

examples/atomic_operations_extension.php

@@ -5,7 +5,7 @@
 use alsvanzelf\jsonapi\objects\ResourceObject;
 use alsvanzelf\jsonapi\extensions\AtomicOperationsDocument;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * use the atomic operations extension as extension to the document

examples/bootstrap_examples.php

@@ -10,15 +10,15 @@
 use alsvanzelf\jsonapi\interfaces\ProfileInterface;
 use alsvanzelf\jsonapi\interfaces\ResourceInterface;
 use alsvanzelf\jsonapi\objects\ResourceIdentifierObject;
-use alsvanzelf\jsonapi\objects\ResourceObject;
 
 ini_set('display_errors', 1);
 error_reporting(-1);
 
 require_once __DIR__.'/../vendor/autoload.php';
 
 class ExampleDataset {
-	private static $records = [
+	/** @var array<string, array<int, array<string, string|int>>> */
+	private static array $records = [
 		'articles' => [
 			1 => [
 				'title'    => 'JSON:API paints my bikeshed!',
@@ -58,34 +58,43 @@ class ExampleDataset {
 		],
 	];
 
-	public static function getRecord($type, $id) {
-		if (!isset(self::$records[$type][$id])) {
+	/**
+	 * @return array<string, string|int>
+	 */
+	public static function getRecord(string $type, int $id): array {
+		if (isset(self::$records[$type][$id]) === false) {
 			throw new \Exception('sorry, we have a limited dataset');
 		}
 
 		return self::$records[$type][$id];
 	}
 
-	public static function getEntity($type, $id) {
+	public static function getEntity(string $type, int $id): ExampleUser {
 		$record = self::getRecord($type, $id);
 
 		$user = new ExampleUser($id);
 		foreach ($record as $key => $value) {
-			$user->$key = $value;
+			$user->$key = $value; // @phpstan-ignore property.dynamicName
 		}
 
 		return $user;
 	}
 
-	public static function findRecords($type) {
+	/**
+	 * @return array<array<string, string|int>>
+	 */
+	public static function findRecords(string $type): array {
 		return self::$records[$type];
 	}
 
-	public static function findEntities($type) {
-		$records  = self::findRecords($type);
-		$entities = [];
+	/**
+	 * @return ExampleUser[]
+	 */
+	public static function findEntities(string $type): array {
+		$recordIds = array_keys(self::findRecords($type));
+		$entities  = [];
 
-		foreach ($records as $id => $record) {
+		foreach ($recordIds as $id) {
 			$entities[$id] = self::getEntity($type, $id);
 		}
 
@@ -94,15 +103,15 @@ public static function findEntities($type) {
 }
 
 class ExampleUser {
-	public $name;
-	public $heads;
-	public $unknown;
+	public ?string $name = null;
+	public null|int|string $heads = null;
+	public mixed $unknown = null;
 
 	public function __construct(
-		public $id,
+		public int $id,
 	) {}
 
-	function getCurrentLocation() {
+	public function getCurrentLocation(): string {
 		return 'Earth';
 	}
 }
@@ -124,11 +133,7 @@ public function getNamespace(): string {
 	 * optionally helpers for the specific extension
 	 */
 
-	public function setVersion(ResourceInterface $resource, $version) {
-		if ($resource instanceof HasExtensionMembersInterface === false) {
-			throw new \Exception('resource doesn\'t have extension members');
-		}
-
+	public function setVersion(ResourceInterface & HasExtensionMembersInterface $resource, string $version): void {
 		if ($resource instanceof ResourceDocument) {
 			$resource->getResource()->addExtensionMember($this, 'id', $version);
 		}
@@ -151,14 +156,11 @@ public function getOfficialLink(): string {
 	 * optionally helpers for the specific profile
 	 */
 
-	/**
-	 * @param ResourceInterface&HasAttributesInterface $resource
-	 */
-	public function setTimestamps(ResourceInterface $resource, ?\DateTimeInterface $created=null, ?\DateTimeInterface $updated=null) {
-		if ($resource instanceof HasAttributesInterface === false) {
-			throw new \Exception('cannot add attributes to identifier objects');
-		}
-
+	public function setTimestamps(
+		ResourceInterface & HasAttributesInterface $resource,
+		?\DateTimeInterface $created=null,
+		?\DateTimeInterface $updated=null,
+	): void {
 		$timestamps = [];
 		if ($created !== null) {
 			$timestamps['created'] = $created->format(\DateTime::ISO8601);

examples/collection.php

@@ -5,7 +5,7 @@
 use alsvanzelf\jsonapi\CollectionDocument;
 use alsvanzelf\jsonapi\objects\ResourceObject;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 $users = ExampleDataset::findEntities('user');
 
@@ -18,7 +18,7 @@
 foreach ($users as $user) {
 	$resource = ResourceObject::fromObject($user, type: 'user', id: $user->id);
 
-	if ($user->id == 42) {
+	if ($user->id === 42) {
 		$ship = new ResourceObject('ship', 5);
 		$ship->add('name', 'Heart of Gold');
 		$resource->addRelationship('ship', $ship);

examples/collection_canonical.php

@@ -5,7 +5,7 @@
 use alsvanzelf\jsonapi\CollectionDocument;
 use alsvanzelf\jsonapi\objects\ResourceObject;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 $articleRecords = ExampleDataset::findRecords('articles');
 $commentRecords = ExampleDataset::findRecords('comments');

examples/cursor_pagination_profile.php

@@ -6,7 +6,7 @@
 use alsvanzelf\jsonapi\objects\ResourceObject;
 use alsvanzelf\jsonapi\profiles\CursorPaginationProfile;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * use the cursor pagination profile as extension to the document

examples/errors_all_options.php

@@ -5,7 +5,7 @@
 use alsvanzelf\jsonapi\ErrorsDocument;
 use alsvanzelf\jsonapi\objects\ErrorObject;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * setting all options

examples/errors_exception_native.php

@@ -4,7 +4,7 @@
 
 use alsvanzelf\jsonapi\ErrorsDocument;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * via an exception
@@ -17,12 +17,12 @@
 try {
 	throw new \Exception('unknown user', 404);
 }
-catch (Exception $e) {
+catch (Exception $exception) {
 	$options = [
 		'includeExceptionTrace'    => true,
 		'includeExceptionPrevious' => true,
 	];
-	$document = ErrorsDocument::fromException($e, $options);
+	$document = ErrorsDocument::fromException($exception, $options);
 
 	$options = [
 		'prettyPrint' => true,

examples/extension.php

@@ -6,7 +6,7 @@
 use alsvanzelf\jsonapi\enums\ContentTypeEnum;
 use alsvanzelf\jsonapi\helpers\Converter;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * use an extension extend the document with new members

examples/meta_only.php

@@ -4,7 +4,7 @@
 
 use alsvanzelf\jsonapi\MetaDocument;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * there are a few use-cases for sending meta-only responses

examples/null_values.php

@@ -7,7 +7,7 @@
 use alsvanzelf\jsonapi\objects\LinkObject;
 use alsvanzelf\jsonapi\objects\RelationshipObject;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * tell that a value is non-existing

examples/output.php

@@ -5,7 +5,7 @@
 use alsvanzelf\jsonapi\MetaDocument;
 use alsvanzelf\jsonapi\enums\ContentTypeEnum;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 $document = new MetaDocument();
 $document->add('foo', 'bar');
@@ -69,10 +69,6 @@
  * send json response
  */
 
-$options = ['prettyPrint' => true, 'contentType' => 'text/html'];
 echo '<h2>Send json response</h2>';
 echo '<pre style="font-size: large;">$document->sendResponse();</pre>';
-echo '<pre>';
-$document->sendResponse($options);
-echo '</pre>';
-echo '<p><em>Also sends http status code ('.$document->getHttpStatusCode().') and headers: [Content-Type: '.ContentTypeEnum::Official->value.']</em></p>';
+echo '<p><em>Echo\'s the result of <code style="font-size: large;">$document->toJson()</code> and sends http status code ('.$document->getHttpStatusCode().') and headers: [Content-Type: '.ContentTypeEnum::Official->value.']</em></p>';

examples/profile.php

@@ -6,7 +6,7 @@
 use alsvanzelf\jsonapi\enums\ContentTypeEnum;
 use alsvanzelf\jsonapi\helpers\Converter;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * use a profile to define rules for members

examples/relationship_to_many_document.php

@@ -4,7 +4,7 @@
 
 use alsvanzelf\jsonapi\CollectionDocument;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * a to-many relationship response

examples/relationship_to_one_document.php

@@ -5,7 +5,7 @@
 use alsvanzelf\jsonapi\ResourceDocument;
 use alsvanzelf\jsonapi\enums\DocumentLevelEnum;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * a to-one relationship response

examples/relationships.php

@@ -8,7 +8,7 @@
 use alsvanzelf\jsonapi\objects\RelationshipObject;
 use alsvanzelf\jsonapi\objects\ResourceObject;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * the different ways of adding relationships to a resource
@@ -74,15 +74,6 @@
 
 $document->addRelationshipObject('one-by-one-neighbours', $relationshipObject);
 
-/**
- * custom
- */
-$jsonapi = new ResourceDocument('user', 1);
-$customRelation = [
-	'data' => ['cus' => 'tom'],
-];
-$jsonapi->addRelationship('custom', $customRelation);
-
 /**
  * sending the response
  */

examples/request_superglobals.php

@@ -5,7 +5,7 @@
 use alsvanzelf\jsonapi\enums\ContentTypeEnum;
 use alsvanzelf\jsonapi\helpers\RequestParser;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 /**
  * preparing request data in superglobals from a webserver
@@ -60,31 +60,55 @@
  */
 
 // useful for filling a self link in responses
-var_dump($requestParser->getSelfLink());
+echo '<h2>Get self link</h2>';
+echo '<pre style="font-size: large;">$requestParser->getSelfLink()</pre>';
+echo '<pre>'.var_export($requestParser->getSelfLink(), return: true).'</pre>';
 
 // useful for determining how to process the request (list/get/create/update)
-var_dump($requestParser->hasIncludePaths());
-var_dump($requestParser->hasSparseFieldset('user'));
-var_dump($requestParser->hasSortFields());
-var_dump($requestParser->hasPagination());
-var_dump($requestParser->hasFilter());
+echo '<h2>Check query parameters</h2>';
+echo '<pre style="font-size: large;">$requestParser->hasIncludePaths()</pre>';
+echo '<pre>'.var_export($requestParser->hasIncludePaths(), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->hasSparseFieldset()</pre>';
+echo '<pre>'.var_export($requestParser->hasSparseFieldset('user'), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->hasSortFields()</pre>';
+echo '<pre>'.var_export($requestParser->hasSortFields(), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->hasPagination()</pre>';
+echo '<pre>'.var_export($requestParser->hasPagination(), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->hasFilter()</pre>';
+echo '<pre>'.var_export($requestParser->hasFilter(), return: true).'</pre>';
 
 // these methods often return arrays where comma separated query parameter values are processed for ease of use
-var_dump($requestParser->getIncludePaths());
-var_dump($requestParser->getSparseFieldset('user'));
-var_dump($requestParser->getSortFields());
-var_dump($requestParser->getPagination());
-var_dump($requestParser->getFilter());
+echo '<h2>Get query parameters</h2>';
+echo '<pre style="font-size: large;">$requestParser->getIncludePaths()</pre>';
+echo '<pre>'.var_export($requestParser->getIncludePaths(), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->getSparseFieldset()</pre>';
+echo '<pre>'.var_export($requestParser->getSparseFieldset('user'), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->getSortFields()</pre>';
+echo '<pre>'.var_export($requestParser->getSortFields(), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->getPagination()</pre>';
+echo '<pre>'.var_export($requestParser->getPagination(), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->getFilter()</pre>';
+echo '<pre>'.var_export($requestParser->getFilter(), return: true).'</pre>';
 
 // use for determinging whether keys were given without having to dive deep into the POST data yourself
-var_dump($requestParser->hasAttribute('name'));
-var_dump($requestParser->hasRelationship('ship'));
-var_dump($requestParser->hasMeta('lock'));
+echo '<h2>Check parts of the document</h2>';
+echo '<pre style="font-size: large;">$requestParser->hasAttribute()</pre>';
+echo '<pre>'.var_export($requestParser->hasAttribute('name'), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->hasRelationship()</pre>';
+echo '<pre>'.var_export($requestParser->hasRelationship('ship'), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->hasMeta()</pre>';
+echo '<pre>'.var_export($requestParser->hasMeta('lock'), return: true).'</pre>';
 
 // get the raw data from the document, this doesn't (yet) return specific objects
-var_dump($requestParser->getAttribute('name'));
-var_dump($requestParser->getRelationship('ship'));
-var_dump($requestParser->getMeta('lock'));
+echo '<h2>Get parts of the document</h2>';
+echo '<pre style="font-size: large;">$requestParser->getAttribute()</pre>';
+echo '<pre>'.var_export($requestParser->getAttribute('name'), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->getRelationship()</pre>';
+echo '<pre>'.var_export($requestParser->getRelationship('ship'), return: true).'</pre>';
+echo '<pre style="font-size: large;">$requestParser->getMeta()</pre>';
+echo '<pre>'.var_export($requestParser->getMeta('lock'), return: true).'</pre>';
 
 // get the full document for custom processing
-var_dump($requestParser->getDocument());
+echo '<h2>Get full document</h2>';
+echo '<pre style="font-size: large;">$requestParser->getDocument()</pre>';
+echo '<pre>'.var_export($requestParser->getDocument(), return: true).'</pre>';

examples/resource_human_api.php

@@ -10,7 +10,7 @@
 use alsvanzelf\jsonapi\objects\RelationshipsObject;
 use alsvanzelf\jsonapi\objects\ResourceObject;
 
-require 'bootstrap_examples.php';
+require __DIR__.'/bootstrap_examples.php';
 
 $user1  = ExampleDataset::getEntity('user', 1);
 $user42 = ExampleDataset::getEntity('user', 42);