Adding a few extension interfaces (#266)

src/Faker/Core/Coordinates.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Faker\Core;
+
+use Faker\Extension\Extension;
+
+class Coordinates implements Extension
+{
+    /**
+     * @example '77.147489'
+     *
+     * @return float Uses signed degrees format (returns a float number between -90 and 90)
+     */
+    public function latitude(float $min = -90.0, float $max = 90.0): float
+    {
+        if ($min < -90 || $max < -90) {
+            throw new \LogicException('Latitude cannot be less that -90.0');
+        }
+
+        if ($min > 90 || $max > 90) {
+            throw new \LogicException('Latitude cannot be greater that 90.0');
+        }
+
+        return $this->randomFloat(6, $min, $max);
+    }
+
+    /**
+     * @example '86.211205'
+     *
+     * @return float Uses signed degrees format (returns a float number between -180 and 180)
+     */
+    public function longitude(float $min = -180.0, float $max = 180.0): float
+    {
+        if ($min < -180 || $max < -180) {
+            throw new \LogicException('Longitude cannot be less that -180.0');
+        }
+
+        if ($min > 180 || $max > 180) {
+            throw new \LogicException('Longitude cannot be greater that 180.0');
+        }
+
+        return $this->randomFloat(6, $min, $max);
+    }
+
+    /**
+     * @example array('77.147489', '86.211205')
+     *
+     * @return array{latitude: float, longitude: float}
+     */
+    public function localCoordinates(): array
+    {
+        return [
+            'latitude' => static::latitude(),
+            'longitude' => static::longitude(),
+        ];
+    }
+
+    private function randomFloat(int $nbMaxDecimals, float $min, float $max): float
+    {
+        if ($min > $max) {
+            throw new \LogicException('Invalid coordinates boundaries');
+        }
+
+        return round($min + mt_rand() / mt_getrandmax() * ($max - $min), $nbMaxDecimals);
+    }
+}

src/Faker/Extension/AddressExtension.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace Faker\Extension;
+
+/**
+ * @experimental This interface is experimental and does not fall under our BC promise
+ */
+interface AddressExtension extends Extension
+{
+    /**
+     * @example '791 Crist Parks, Sashabury, IL 86039-9874'
+     */
+    public function address(): string;
+
+    /**
+     * Randomly return a real city name.
+     */
+    public function city(): string;
+
+    /**
+     * @example 86039-9874
+     */
+    public function postcode(): string;
+
+    /**
+     * @example 'Crist Parks'
+     */
+    public function streetName(): string;
+
+    /**
+     * @example '791 Crist Parks'
+     */
+    public function streetAddress(): string;
+
+    /**
+     * Randomly return a building number.
+     */
+    public function buildingNumber(): string;
+}

src/Faker/Extension/CompanyExtension.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Faker\Extension;
+
+/**
+ * @experimental This interface is experimental and does not fall under our BC promise
+ */
+interface CompanyExtension extends Extension
+{
+    /**
+     * @example 'Acme Ltd'
+     */
+    public function company(): string;
+
+    /**
+     * @example 'Ltd'
+     */
+    public function companySuffix(): string;
+
+    public function jobTitle(): string;
+}

src/Faker/Extension/CountryExtension.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace Faker\Extension;
+
+/**
+ * @experimental This interface is experimental and does not fall under our BC promise
+ */
+interface CountryExtension extends Extension
+{
+    /**
+     * @example 'Japan'
+     */
+    public function country(): string;
+}

src/Faker/Extension/GeneratorAwareExtension.php

@@ -16,5 +16,5 @@ interface GeneratorAwareExtension extends Extension
      * immutability of the extension, and MUST return an instance that has the
      * new Generator.
      */
-    public function withGenerator(Generator $generator): self;
+    public function withGenerator(Generator $generator): Extension;
 }

src/Faker/Extension/GeneratorAwareExtensionTrait.php

@@ -19,7 +19,7 @@ trait GeneratorAwareExtensionTrait
     /**
      * @return static
      */
-    public function withGenerator(Generator $generator): self
+    public function withGenerator(Generator $generator): Extension
     {
         $instance = clone $this;
 

src/Faker/Extension/PersonExtension.php

@@ -0,0 +1,54 @@
+<?php
+
+namespace Faker\Extension;
+
+/**
+ * @experimental This interface is experimental and does not fall under our BC promise
+ */
+interface PersonExtension extends Extension
+{
+    public const GENDER_FEMALE = 'female';
+    public const GENDER_MALE = 'male';
+
+    /**
+     * @param string|null $gender 'male', 'female' or null for any
+     *
+     * @return string
+     *
+     * @example 'John Doe'
+     */
+    public function name(?string $gender = null);
+
+    /**
+     * @param string|null $gender 'male', 'female' or null for any
+     *
+     * @example 'John'
+     */
+    public function firstName(?string $gender = null): string;
+
+    public function firstNameMale(): string;
+
+    public function firstNameFemale(): string;
+
+    /**
+     * @example 'Doe'
+     */
+    public function lastName(): string;
+
+    /**
+     * @example 'Mrs.'
+     *
+     * @param string|null $gender 'male', 'female' or null for any
+     */
+    public function title(?string $gender = null): string;
+
+    /**
+     * @example 'Mr.'
+     */
+    public function titleMale(): string;
+
+    /**
+     * @example 'Mrs.'
+     */
+    public function titleFemale(): string;
+}

src/Faker/Extension/PhoneNumberExtension.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Faker\Extension;
+
+/**
+ * @experimental This interface is experimental and does not fall under our BC promise
+ */
+interface PhoneNumberExtension extends Extension
+{
+    /**
+     * @example '555-123-546'
+     */
+    public function phoneNumber(): string;
+
+    /**
+     * @example +27113456789
+     */
+    public function e164PhoneNumber(): string;
+}