API

Overview of the bitframe-geolocation package including classes and their methods and properties

View Source

namespace BitFrame\Locale;

use \Psr\Http\Message\ServerRequestInterface;
use \Psr\Http\Message\ResponseInterface;
use \Psr\Http\Server\RequestHandlerInterface;

// implements:
use \Psr\Http\Server\MiddlewareInterface;

// uses:
use \BitFrame\Delegate\CallableMiddlewareTrait;
use \BitFrame\Locale\GeoLocationTrait;

/**
 * Geo Location wrapper class to fetch user geo 
 * data as a middleware.
 */
class GeoLocation implements MiddlewareInterface
{
    use CallableMiddlewareTrait;
    use GeoLocationTrait;
    
    /** @var bool */
    private $remoteIpLookup;
    
    /**
     * @param bool $remoteIpLookup (optional, default: false)
     */
    public function __construct(  );
    
    /**
     * Process an incoming server request and return a
     * response, optionally delegating response creation
     * to a handler.
     *
     * @param ServerRequestInterface $request
     * @param RequestHandlerInterface $handler
     *
     * @return ResponseInterface
     */
    public function process(  ): ResponseInterface;
    
    /**
     * Set setting that determines whether IP 
     * will be looked up via an online service or not. 
     *
     * @return bool
     */
    public function setRemoteIpLookup(  ): self;
    
    /**
     * Get remote ip lookup setting.
     *
     * @return bool
     */
    public function getRemoteIpLookup(): bool;
}
namespace BitFrame\Locale;

// extends:
use \BitFrame\Data\ApplicationData

// exceptions:
use \BadMethodCallException;

/**
 * Stores geo location data.
 */
class GeoLocationData extends ApplicationData
{
    /**
     * Store the specified data.
     *
     * Note that this specific implementation 
     * makes setting data method immutable.
     *
     * @see: ApplicationData::offsetSet()
     *
     * @throws BadMethodCallException
     */
    public function offsetSet(  );

    /**
     * Remove the data by the specified key.
     *
     * Note that this specific implementation 
     * makes unsetting data method immutable.
     *
     * @see: ApplicationData::offsetUnset()
     *
     * @throws BadMethodCallException
     */
    public function offsetUnset(  );
}
namespace BitFrame\Locale;

use \Psr\Http\Message\ServerRequestInterface;
use \Geocoder\Query\GeocodeQuery;
use \Geocoder\Provider\Provider;
use \Geocoder\Provider\Chain\Chain;
use \Geocoder\Provider\FreeGeoIp\FreeGeoIp;
use \Geocoder\Provider\GeoPlugin\GeoPlugin;
use \Geocoder\Collection;

// uses:
use \BitFrame\Locale\RemoteAddressTrait;

// exceptions:
use \InvalidArgumentException;
use \BitFrame\Locale\Exception\IpAddressNotFoundException;

/**
 * Common wrapper for the Geocoder plugin. 
 */
trait GeoLocationTrait
{
    use RemoteAddressTrait;
    
    /** @var Provider */
    private $provider;
    
    /**
     * Set Geocoder Provider.
     *
     * @param Provider|array $provider
     *
     * @return $this
     *
     * @throws InvalidArgumentException
     */
    public function setProvider(  ): self;
    
    /**
     * Get Geocoder Provider (sets a default provider 
     * if no provider available).
     *
     * @return Provider
     */
    public function getProvider(): Provider;

    /**
     * Get location data.
     *
     * @param ServerRequestInterface $request
     * @param string $ip
     *
     * @return Collection
     *
     * @throws IpAddressNotFoundException
     * @throws InvalidArgumentException
     */
    public function getGeoLocationData(  ): Collection;
}
namespace BitFrame\Locale;

use \Psr\Http\Message\ServerRequestInterface;

/**
 * Get user ip.
 */
trait RemoteAddressTrait 
{
    /** @var bool */
    private $useProxy = false;
    
    /** @var array */
    private $trustedProxies = [];
    
    /** @var array */
    private $proxyHeader = [
        'Forwarded',
        'Forwarded-For',
        'X-Forwarded',
        'X-Forwarded-For',
        'X-Cluster-Client-Ip',
        'Client-Ip'
    ];
    
    /** @var string */
    private $remoteAddr = 'https://api.ipify.org/?format=text';
    
    /**
     * Changes proxy handling setting which 
     * determines whether to use proxy addresses 
     * or not. 
     *
     * @param bool $useProxy (optional, default: true)
     *
     * @return $this
     */
    public function setUseProxy(  ): self;
    
    /**
     * Checks proxy handling setting.
     *
     * @return bool
     */
    public function isUseProxy(): bool;
    
    /**
     * Set list of trusted proxy addresses.
     *
     * @param string[] $trustedProxies
     *
     * @return $this
     */
    public function setTrustedProxies(  ): self;
    
    /**
     * Get list of trusted proxy IP addresses.
     *
     * @return string[]
     */
    public function getTrustedProxies(): array;
    
    /**
     * Set the header to introspect for proxy IPs.
     *
     * @param string[] $header (optional, default: [  ])
     *
     * @return $this
     */
    public function setProxyHeader(  ): self;
    
    /**
     * Get HTTP headers to introspect for proxies.
     *
     * @return string[]
     */
    public function getProxyHeader(): array;
    
    /**
     * Set the remote address from where the ip will be 
     * looked up.
     *
     * @param string $addr
     *
     * @return $this
     */
    public function setRemoteAddr(  ): self;
    
    /**
     * Get the remote address from where the ip will be looked up.
     *
     * @return string
     */
    public function getRemoteAddr(): string;
    
    /**
     * Returns client IP address.
     *
     * @param ServerRequestInterface $request
     * @param bool $remoteLookup (optional, default: false)
     *
     * @return string
     */
    public function getIpAddress(  ): string;
    
    /**
     * Returns the IP address from remote service.
     *
     * @return string|null
     */
    private function getRemoteIp(): ?string;
    
    /**
     * Attempt to get the IP address for a proxied client
     *
     * @param ServerRequestInterface $request
     *
     * @return string|null
     *
     * @see IETF HTTP Forwarded For Draft
     */
    private function getProxiedIp(  ): ?string;
    
    /**
     * Returns the remote address of the request, if valid.
     *
     * @param ServerRequestInterface $request
     *
     * @return string|null
     */
    private function getLocalIp(  ): ?string;
    
    /**
     * Normalize a header string. 
     *
     * @param  string $header
     *
     * @return string
     */
    private function normalizeProxyHeader(  ): string;
    
    /**
     * Check that a given string is a valid IP address.
     *
     * @param string $ip
     *
     * @return bool
     */
    private function isIpValid(  ): bool;
}
namespace BitFrame\Locale\Exception;

// extends:
use \BitFrame\Exception\HttpException

/**
 * IP Address not found error.
 */
class IpAddressNotFoundException extends HttpException
{
}

Comments

Let us know if you have something to say or add