Start integrating recursivetree/seat-prices-core into the seat core (#…

…170)

* move first things over

* add documentation

* styleci

src/Contracts/HasTypeID.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of SeAT
+ *
+ * Copyright (C) 2015 to present Leon Jacobs
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+namespace Seat\Services\Contracts;
+
+/**
+ * An interface to describe objects having a type id.
+ */
+interface HasTypeID
+{
+    /**
+     * @return int The eve type id of this object
+     */
+    public function getTypeID(): int;
+}

src/Contracts/IPriceable.php

@@ -0,0 +1,44 @@
+<?php
+
+/*
+ * This file is part of SeAT
+ *
+ * Copyright (C) 2015 to present Leon Jacobs
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+namespace Seat\Services\Contracts;
+
+/**
+ * Describes items that are appraisable using recursivetree/seat-prices-core.
+ * This interface is in the services package to encourage making classes that describe items compatible across both the
+ * seat core and plugin, even if they don't depend on recursivetree/seat-prices-core.
+ */
+interface IPriceable extends HasTypeID
+{
+    /**
+     * @return int The amount of items to be appraised by a price provider
+     */
+    public function getAmount(): int;
+
+    /**
+     * Set the price of this object.
+     *
+     * @param  float  $price
+     * @return void
+     */
+    public function setPrice(float $price): void;
+}

src/Helpers/UserAgentBuilder.php

@@ -0,0 +1,179 @@
+<?php
+
+/*
+ * This file is part of SeAT
+ *
+ * Copyright (C) 2015 to present Leon Jacobs
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+namespace Seat\Services\Helpers;
+
+use Composer\InstalledVersions;
+use OutOfBoundsException;
+use Seat\Services\AbstractSeatPlugin;
+use Seat\Services\Exceptions\SettingException;
+
+/**
+ * A helper to build user agents for seat packages
+ * Structure and terms according to https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent.
+ */
+class UserAgentBuilder
+{
+    protected ?string $product = null;
+    protected ?string $version = null;
+    protected array $comments = [];
+
+    /**
+     * Set the product part of the user agent.
+     *
+     * @param  string  $product  The new product name
+     * @return $this
+     */
+    public function product(string $product): UserAgentBuilder {
+        $this->product = $product;
+
+        return $this;
+    }
+
+    /**
+     * Set the version of the product.
+     *
+     * @param  string  $version
+     * @return $this
+     */
+    public function version(string $version): UserAgentBuilder {
+        $this->version = $version;
+
+        return $this;
+    }
+
+    /**
+     * Configures the product and version of the user agent for a seat plugin.
+     *
+     * @param  string|AbstractSeatPlugin  $plugin  A plugin service provider instance or the FCQN of the service provider (e.g. MyServiceProvider::class)
+     * @return $this
+     */
+    public function seatPlugin(string|AbstractSeatPlugin $plugin): UserAgentBuilder {
+        if(is_string($plugin)){
+            $plugin = new $plugin(null);
+        }
+
+        $this->packagist($plugin->getPackagistVendorName(), $plugin->getPackagistPackageName());
+
+        return $this;
+    }
+
+    /**
+     * Configures the product and version of the user agent for a packagist package.
+     *
+     * @param  string  $vendor  The packagist vendor name
+     * @param  string  $package  The packagist package name
+     * @return $this
+     */
+    public function packagist(string $vendor, string $package): UserAgentBuilder {
+        $this->product = sprintf('%s:%s', $vendor, $package);
+        $this->version = $this->getPackageVersion($vendor, $package);
+
+        return $this;
+    }
+
+    /**
+     * Adds a comment containing the product and version of the user agent for a seat plugin.
+     *
+     * @param  string|AbstractSeatPlugin  $plugin  A plugin service provider instance or the FCQN of the service provider (e.g. MyServiceProvider::class)
+     * @return $this
+     */
+    public function commentSeatPlugin(string|AbstractSeatPlugin $plugin): UserAgentBuilder {
+        if(is_string($plugin)){
+            $plugin = new $plugin(null);
+        }
+
+        $this->commentPackagist($plugin->getPackagistVendorName(), $plugin->getPackagistPackageName());
+
+        return $this;
+    }
+
+    /**
+     * Adds a comment containing the product and version of the user agent for a packagist package.
+     *
+     * @param  string  $vendor  The packagist vendor name
+     * @param  string  $package  The packagist package name
+     * @return $this
+     */
+    public function commentPackagist(string $vendor, string $package): UserAgentBuilder {
+        $this->comment(sprintf('%s:%s/%s', $vendor, $package, $this->getPackageVersion($vendor, $package)));
+
+        return $this;
+    }
+
+    /**
+     * Add a comment to the user agent.
+     *
+     * @param  string  $comment  the comment
+     * @return $this
+     */
+    public function comment(string $comment): UserAgentBuilder {
+        $this->comments[] = $comment;
+
+        return $this;
+    }
+
+    /**
+     * Adds a reasonable set of default comments for any seat plugin.
+     *
+     * @return $this
+     *
+     * @throws SettingException
+     */
+    public function defaultComments(): UserAgentBuilder {
+        $this->comment(sprintf('(admin contact: %s)', setting('admin_contact', true) ?? 'not specified'));
+        $this->comment('(https://github.com/eveseat/seat)');
+        $this->commentPackagist('eveseat', 'seat');
+        $this->commentPackagist('eveseat', 'web');
+        $this->commentPackagist('eveseat', 'eveapi');
+
+        return $this;
+    }
+
+    /**
+     * Assembles the user agent form its product, version, and comments into a string.
+     *
+     * @return string The user agent
+     */
+    public function build(): string {
+        if($this->product === null || $this->version === null) {
+            throw new \Error('version or product not set.');
+        }
+
+        return sprintf('%s/%s %s', $this->product, $this->version, implode(' ', $this->comments));
+    }
+
+    /**
+     * Gets the installed version of a packagist package.
+     *
+     * @param  string  $vendor  The packagist vendor name
+     * @param  string  $package  The packagist package name
+     * @return string
+     */
+    private function getPackageVersion(string $vendor, string $package): string {
+        try {
+            return InstalledVersions::getPrettyVersion(sprintf('%s/%s', $vendor, $package)) ?? 'unknown';
+        } catch (OutOfBoundsException $e) {
+            return 'unknown';
+        }
+    }
+}

src/Items/EveType.php

@@ -0,0 +1,53 @@
+<?php
+
+/*
+ * This file is part of SeAT
+ *
+ * Copyright (C) 2015 to present Leon Jacobs
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+namespace Seat\Services\Items;
+
+use Seat\Services\Contracts\HasTypeID;
+
+/**
+ * A basic implementation of HasTypeID.
+ */
+class EveType implements HasTypeID
+{
+    protected int $type_id;
+
+    /**
+     * @param  int|HasTypeID  $type_id
+     */
+    public function __construct(int|HasTypeID $type_id)
+    {
+        if($type_id instanceof HasTypeID){
+            $type_id = $type_id->getTypeID();
+        }
+
+        $this->type_id = $type_id;
+    }
+
+    /**
+     * @return int The type id
+     */
+    public function getTypeID(): int
+    {
+        return $this->type_id;
+    }
+}

src/Items/PriceableEveType.php

@@ -0,0 +1,71 @@
+<?php
+
+/*
+ * This file is part of SeAT
+ *
+ * Copyright (C) 2015 to present Leon Jacobs
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ */
+
+namespace Seat\Services\Items;
+
+use Seat\Services\Contracts\HasTypeID;
+use Seat\Services\Contracts\IPriceable;
+
+/**
+ * A basic implementation od IPriceable.
+ */
+class PriceableEveType extends EveType implements IPriceable
+{
+    protected float $price;
+    protected float $amount;
+
+    /**
+     * @param  int|HasTypeID  $type_id  The eve type to be appraised
+     * @param  float  $amount  The amount of this type to be appraised
+     */
+    public function __construct(int|HasTypeID $type_id, float $amount)
+    {
+        parent::__construct($type_id);
+        $this->price = 0;
+        $this->amount = $amount;
+    }
+
+    /**
+     * @return int The amount of this item to be appraised
+     */
+    public function getAmount(): int
+    {
+        return $this->amount;
+    }
+
+    /**
+     * @return float The price of this item stack
+     */
+    public function getPrice(): float
+    {
+        return $this->price;
+    }
+
+    /**
+     * @param  float  $price  The new price of this item stack
+     * @return void
+     */
+    public function setPrice(float $price): void
+    {
+       $this->price = $price;
+    }
+}