Merge branch 'part_associations'

src/Entity/LogSystem/LogTargetType.php

@@ -29,6 +29,7 @@ use App\Entity\Parts\Footprint;
 use App\Entity\Parts\Manufacturer;
 use App\Entity\Parts\MeasurementUnit;
 use App\Entity\Parts\Part;
+use App\Entity\Parts\PartAssociation;
 use App\Entity\Parts\PartLot;
 use App\Entity\Parts\StorageLocation;
 use App\Entity\Parts\Supplier;
@@ -63,6 +64,8 @@ enum LogTargetType: int
     case PARAMETER = 18;
     case LABEL_PROFILE = 19;
 
+    case PART_ASSOCIATION = 20;
+
     /**
      * Returns the class name of the target type or null if the target type is NONE.
      * @return string|null
@@ -90,6 +93,7 @@ enum LogTargetType: int
             self::MEASUREMENT_UNIT => MeasurementUnit::class,
             self::PARAMETER => AbstractParameter::class,
             self::LABEL_PROFILE => LabelProfile::class,
+            self::PART_ASSOCIATION => PartAssociation::class,
         };
     }
 

src/Entity/Parts/AssociationType.php

@@ -0,0 +1,46 @@
+<?php
+/*
+ * This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
+ *
+ *  Copyright (C) 2019 - 2023 Jan Böhmer (https://github.com/jbtronics)
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published
+ *  by the Free Software Foundation, either version 3 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 Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+
+namespace App\Entity\Parts;
+
+/**
+ * The values of this enums are used to describe how two parts are associated with each other.
+ */
+enum AssociationType: int
+{
+    /** A user definable association type, which can be described in the comment field */
+    case OTHER = 0;
+    /** The owning part is compatible with the other part  */
+    case COMPATIBLE = 1;
+    /** The owning part supersedes the other part (owner is newer version) */
+    case SUPERSEDES = 2;
+
+    /**
+     * Returns the translation key for this association type.
+     * @return string
+     */
+    public function getTranslationKey(): string
+    {
+        return 'part_association.type.' . strtolower($this->name);
+    }
+}

src/Entity/Parts/Part.php

@@ -41,6 +41,7 @@ use App\ApiPlatform\Filter\EntityFilter;
 use App\ApiPlatform\Filter\LikeFilter;
 use App\ApiPlatform\Filter\PartStoragelocationFilter;
 use App\Entity\Attachments\AttachmentTypeAttachment;
+use App\Entity\Parts\PartTraits\AssociationTrait;
 use App\Repository\PartRepository;
 use Doctrine\DBAL\Types\Types;
 use App\Entity\Attachments\Attachment;
@@ -58,6 +59,7 @@ use DateTime;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\ORM\Mapping as ORM;
+use Jfcherng\Diff\Utility\Arr;
 use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
 use Symfony\Component\Serializer\Annotation\Groups;
 use Symfony\Component\Validator\Constraints as Assert;
@@ -112,6 +114,7 @@ class Part extends AttachmentContainingDBElement
     use OrderTrait;
     use ParametersTrait;
     use ProjectTrait;
+    use AssociationTrait;
 
     /** @var Collection<int, PartParameter>
      */
@@ -165,6 +168,9 @@ class Part extends AttachmentContainingDBElement
         $this->parameters = new ArrayCollection();
         $this->project_bom_entries = new ArrayCollection();
 
+        $this->associated_parts_as_owner = new ArrayCollection();
+        $this->associated_parts_as_other = new ArrayCollection();
+
         //By default, the part has no provider
         $this->providerReference = InfoProviderReference::noProvider();
     }
@@ -193,6 +199,13 @@ class Part extends AttachmentContainingDBElement
                 $this->addParameter(clone $parameter);
             }
 
+            //Deep clone the owned part associations (the owned ones make not much sense without the owner)
+            $ownedAssociations = $this->associated_parts_as_owner;
+            $this->associated_parts_as_owner = new ArrayCollection();
+            foreach ($ownedAssociations as $association) {
+                $this->addAssociatedPartsAsOwner(clone $association);
+            }
+
             //Deep clone info provider
             $this->providerReference = clone $this->providerReference;
         }

src/Entity/Parts/PartAssociation.php

@@ -0,0 +1,233 @@
+<?php
+/*
+ * This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
+ *
+ *  Copyright (C) 2019 - 2023 Jan Böhmer (https://github.com/jbtronics)
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published
+ *  by the Free Software Foundation, either version 3 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 Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+
+namespace App\Entity\Parts;
+
+use ApiPlatform\Doctrine\Orm\Filter\BooleanFilter;
+use ApiPlatform\Doctrine\Orm\Filter\DateFilter;
+use ApiPlatform\Doctrine\Orm\Filter\OrderFilter;
+use ApiPlatform\Doctrine\Orm\Filter\RangeFilter;
+use ApiPlatform\Metadata\ApiFilter;
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use ApiPlatform\Metadata\Delete;
+use ApiPlatform\Metadata\Get;
+use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\Patch;
+use ApiPlatform\Metadata\Post;
+use ApiPlatform\Serializer\Filter\PropertyFilter;
+use App\ApiPlatform\Filter\LikeFilter;
+use App\Repository\DBElementRepository;
+use Doctrine\DBAL\Types\Types;
+use Doctrine\ORM\Mapping as ORM;
+use App\Entity\Base\AbstractDBElement;
+use App\Entity\Base\TimestampTrait;
+use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
+use Symfony\Component\Serializer\Annotation\Groups;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * This entity describes a part association, which is a semantic connection between two parts.
+ * For example, a part association can be used to describe that a part is a replacement for another part.
+ */
+#[ORM\Entity(repositoryClass: DBElementRepository::class)]
+#[ORM\HasLifecycleCallbacks]
+#[UniqueEntity(fields: ['other', 'owner', 'type'], message: 'validator.part_association.already_exists')]
+#[ApiResource(
+    operations: [
+        new Get(security: 'is_granted("read", object)'),
+        new GetCollection(security: 'is_granted("@parts.read")'),
+        new Post(securityPostDenormalize: 'is_granted("create", object)'),
+        new Patch(security: 'is_granted("edit", object)'),
+        new Delete(security: 'is_granted("delete", object)'),
+    ],
+    normalizationContext: ['groups' => ['part_assoc:read', 'part_assoc:read:standalone',  'api:basic:read'], 'openapi_definition_name' => 'Read'],
+    denormalizationContext: ['groups' => ['part_assoc:write', 'api:basic:write'], 'openapi_definition_name' => 'Write'],
+)]
+#[ApiFilter(PropertyFilter::class)]
+#[ApiFilter(LikeFilter::class, properties: ["other_type", "comment"])]
+#[ApiFilter(DateFilter::class, strategy: DateFilter::EXCLUDE_NULL)]
+#[ApiFilter(OrderFilter::class, properties: ['comment', 'addedDate', 'lastModified'])]
+class PartAssociation extends AbstractDBElement
+{
+    use TimestampTrait;
+
+    /**
+     * @var AssociationType The type of this association (how the two parts are related)
+     */
+    #[ORM\Column(type: Types::SMALLINT, enumType: AssociationType::class)]
+    #[Groups(['part_assoc:read', 'part_assoc:write'])]
+    protected AssociationType $type = AssociationType::OTHER;
+
+    /**
+     * @var string|null A user definable association type, which can be described in the comment field, which
+     * is used if the type is OTHER
+     */
+    #[ORM\Column(type: Types::STRING, length: 255, nullable: true)]
+    #[Assert\Expression("this.getType().value !== 0 or this.getOtherType() !== null",
+        message: 'validator.part_association.must_set_an_value_if_type_is_other')]
+    #[Groups(['part_assoc:read', 'part_assoc:write'])]
+    protected ?string $other_type = null;
+
+    /**
+     * @var string|null A comment describing this association further.
+     */
+    #[ORM\Column(type: Types::TEXT, nullable: true)]
+    #[Groups(['part_assoc:read', 'part_assoc:write'])]
+    protected ?string $comment = null;
+
+    /**
+     * @var Part|null The part which "owns" this association, e.g. the part which is a replacement for another part
+     */
+    #[ORM\ManyToOne(targetEntity: Part::class, inversedBy: 'associated_parts_as_owner')]
+    #[ORM\JoinColumn(nullable: false, onDelete: 'CASCADE')]
+    #[Assert\NotNull]
+    #[Groups(['part_assoc:read:standalone', 'part_assoc:write'])]
+    protected ?Part $owner = null;
+
+    /**
+     * @var Part|null The part which is "owned" by this association, e.g. the part which is replaced by another part
+     */
+    #[ORM\ManyToOne(targetEntity: Part::class, inversedBy: 'associated_parts_as_other')]
+    #[ORM\JoinColumn(nullable: false, onDelete: 'CASCADE')]
+    #[Assert\NotNull]
+    #[Assert\Expression("this.getOwner() !== this.getOther()",
+        message: 'validator.part_association.part_cannot_be_associated_with_itself')]
+    #[Groups(['part_assoc:read', 'part_assoc:write'])]
+    protected ?Part $other = null;
+
+    /**
+     * Returns the (semantic) relation type of this association as an AssociationType enum value.
+     * If the type is set to OTHER, then the other_type field value is used for the user defined type.
+     * @return AssociationType
+     */
+    public function getType(): AssociationType
+    {
+        return $this->type;
+    }
+
+    /**
+     * Sets the (semantic) relation type of this association as an AssociationType enum value.
+     * @param  AssociationType  $type
+     * @return $this
+     */
+    public function setType(AssociationType $type): PartAssociation
+    {
+        $this->type = $type;
+        return $this;
+    }
+
+    /**
+     * Returns a comment, which describes this association further.
+     * @return string|null
+     */
+    public function getComment(): ?string
+    {
+        return $this->comment;
+    }
+
+    /**
+     * Sets a comment, which describes this association further.
+     * @param  string|null  $comment
+     * @return $this
+     */
+    public function setComment(?string $comment): PartAssociation
+    {
+        $this->comment = $comment;
+        return $this;
+    }
+
+    /**
+     * Returns the part which "owns" this association, e.g. the part which is a replacement for another part.
+     * @return Part|null
+     */
+    public function getOwner(): ?Part
+    {
+        return $this->owner;
+    }
+
+    /**
+     * Sets the part which "owns" this association, e.g. the part which is a replacement for another part.
+     * @param  Part|null  $owner
+     * @return $this
+     */
+    public function setOwner(?Part $owner): PartAssociation
+    {
+        $this->owner = $owner;
+        return $this;
+    }
+
+    /**
+     * Returns the part which is "owned" by this association, e.g. the part which is replaced by another part.
+     * @return Part|null
+     */
+    public function getOther(): ?Part
+    {
+        return $this->other;
+    }
+
+    /**
+     * Sets the part which is "owned" by this association, e.g. the part which is replaced by another part.
+     * @param  Part|null  $other
+     * @return $this
+     */
+    public function setOther(?Part $other): PartAssociation
+    {
+        $this->other = $other;
+        return $this;
+    }
+
+    /**
+     * Returns the user defined association type, which is used if the type is set to OTHER.
+     * @return string|null
+     */
+    public function getOtherType(): ?string
+    {
+        return $this->other_type;
+    }
+
+    /**
+     * Sets the user defined association type, which is used if the type is set to OTHER.
+     * @param  string|null  $other_type
+     * @return $this
+     */
+    public function setOtherType(?string $other_type): PartAssociation
+    {
+        $this->other_type = $other_type;
+        return $this;
+    }
+
+    /**
+     * Returns the translation key for the type of this association.
+     * If the type is set to OTHER, then the other_type field value is used.
+     * @return string
+     */
+    public function getTypeTranslationKey(): string
+    {
+        if ($this->type === AssociationType::OTHER) {
+            return $this->other_type ?? 'Unknown';
+        }
+        return $this->type->getTranslationKey();
+    }
+
+}

src/Entity/Parts/PartLot.php

@@ -47,6 +47,7 @@ use App\Validator\Constraints\ValidPartLot;
 use DateTime;
 use Doctrine\ORM\Mapping as ORM;
 use Exception;
+use Symfony\Bridge\Doctrine\Validator\Constraints\UniqueEntity;
 use Symfony\Component\Serializer\Annotation\Groups;
 use Symfony\Component\Validator\Constraints as Assert;
 use Symfony\Component\Validator\Context\ExecutionContextInterface;
@@ -60,9 +61,11 @@ use Symfony\Component\Validator\Context\ExecutionContextInterface;
 #[ORM\Entity]
 #[ORM\HasLifecycleCallbacks]
 #[ORM\Table(name: 'part_lots')]
-#[ORM\Index(name: 'part_lots_idx_instock_un_expiration_id_part', columns: ['instock_unknown', 'expiration_date', 'id_part'])]
-#[ORM\Index(name: 'part_lots_idx_needs_refill', columns: ['needs_refill'])]
+#[ORM\Index(columns: ['instock_unknown', 'expiration_date', 'id_part'], name: 'part_lots_idx_instock_un_expiration_id_part')]
+#[ORM\Index(columns: ['needs_refill'], name: 'part_lots_idx_needs_refill')]
+#[ORM\Index(columns: ['vendor_barcode'], name: 'part_lots_idx_barcode')]
 #[ValidPartLot]
+#[UniqueEntity(['vendor_barcode'], message: 'validator.part_lot.vendor_barcode_must_be_unique')]
 #[ApiResource(
     operations: [
         new Get(security: 'is_granted("read", object)'),
@@ -154,6 +157,13 @@ class PartLot extends AbstractDBElement implements TimeStampableInterface, Named
     #[Groups(['part_lot:read', 'part_lot:write'])]
     protected ?User $owner = null;
 
+    /**
+     * @var string|null The content of the barcode of this part lot (e.g. a barcode on the package put by the vendor)
+     */
+    #[ORM\Column(type: Types::STRING, nullable: true)]
+    #[Groups(['part_lot:read', 'part_lot:write'])]
+    protected ?string $vendor_barcode = null;
+
     public function __clone()
     {
         if ($this->id) {
@@ -354,6 +364,29 @@ class PartLot extends AbstractDBElement implements TimeStampableInterface, Named
         return $this->description;
     }
 
+    /**
+     * The content of the barcode of this part lot (e.g. a barcode on the package put by the vendor), or
+     * null if no barcode is set.
+     * @return string|null
+     */
+    public function getVendorBarcode(): ?string
+    {
+        return $this->vendor_barcode;
+    }
+
+    /**
+     * Set the content of the barcode of this part lot (e.g. a barcode on the package put by the vendor).
+     * @param  string|null  $vendor_barcode
+     * @return $this
+     */
+    public function setVendorBarcode(?string $vendor_barcode): PartLot
+    {
+        $this->vendor_barcode = $vendor_barcode;
+        return $this;
+    }
+
+
+
     #[Assert\Callback]
     public function validate(ExecutionContextInterface $context, $payload): void
     {

src/Entity/Parts/PartTraits/AssociationTrait.php

@@ -0,0 +1,111 @@
+<?php
+/*
+ * This file is part of Part-DB (https://github.com/Part-DB/Part-DB-symfony).
+ *
+ *  Copyright (C) 2019 - 2023 Jan Böhmer (https://github.com/jbtronics)
+ *
+ *  This program is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU Affero General Public License as published
+ *  by the Free Software Foundation, either version 3 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 Affero General Public License for more details.
+ *
+ *  You should have received a copy of the GNU Affero General Public License
+ *  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+declare(strict_types=1);
+
+
+namespace App\Entity\Parts\PartTraits;
+
+use App\Entity\Parts\Part;
+use App\Entity\Parts\PartAssociation;
+use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
+use Symfony\Component\Serializer\Annotation\Groups;
+use Symfony\Component\Validator\Constraints\Valid;
+use Doctrine\ORM\Mapping as ORM;
+
+trait AssociationTrait
+{
+    /**
+     * @var Collection<PartAssociation> All associations where this part is the owner
+     */
+    #[Valid]
+    #[ORM\OneToMany(mappedBy: 'owner', targetEntity: PartAssociation::class,
+        cascade: ['persist', 'remove'], orphanRemoval: true)]
+    #[Groups(['part:read', 'part:write'])]
+    protected Collection $associated_parts_as_owner;
+
+    /**
+     * @var Collection<PartAssociation> All associations where this part is the owned/other part
+     */
+    #[Valid]
+    #[ORM\OneToMany(mappedBy: 'other', targetEntity: PartAssociation::class,
+        cascade: ['persist', 'remove'], orphanRemoval: true)]
+    #[Groups(['part:read'])]
+    protected Collection $associated_parts_as_other;
+
+    /**
+     * Returns all associations where this part is the owner.
+     * @return Collection<PartAssociation>
+     */
+    public function getAssociatedPartsAsOwner(): Collection
+    {
+        return $this->associated_parts_as_owner;
+    }
+
+    /**
+     * Add a new association where this part is the owner.
+     * @param  PartAssociation  $association
+     * @return $this
+     */
+    public function addAssociatedPartsAsOwner(PartAssociation $association): self
+    {
+        //Ensure that the association is really owned by this part
+        $association->setOwner($this);
+
+        $this->associated_parts_as_owner->add($association);
+        return $this;
+    }
+
+    /**
+     * Remove an association where this part is the owner.
+     * @param  PartAssociation  $association
+     * @return $this
+     */
+    public function removeAssociatedPartsAsOwner(PartAssociation $association): self
+    {
+        $this->associated_parts_as_owner->removeElement($association);
+        return $this;
+    }
+
+    /**
+     * Returns all associations where this part is the owned/other part.
+     * If you want to modify the association, do it on the owning part
+     * @return Collection<PartAssociation>
+     */
+    public function getAssociatedPartsAsOther(): Collection
+    {
+        return $this->associated_parts_as_other;
+    }
+
+    /**
+     * Returns all associations where this part is the owned or other part.
+     * @return Collection<PartAssociation>
+     */
+    public function getAssociatedPartsAll(): Collection
+    {
+        return new ArrayCollection(
+            array_merge(
+                $this->associated_parts_as_owner->toArray(),
+                $this->associated_parts_as_other->toArray()
+            )
+        );
+    }
+}