Add more details to documentation, tweak names

[tacman]

I'm trying to follow the documentation, and can't figure out how this works (from the README)

<?php
    
use Doctrine\ORM\Mapping as ORM;
use Webfactory\Bundle\PolyglotBundle\Entity\BaseTranslation;

#[ORM\Table]
#[ORM\UniqueConstraint(columns: ['entity_id', 'locale'])]
#[ORM\Entity]
class DocumentTranslation
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private int $id;

    #[ORM\Column]
    #[Polyglot\Locale]
    private string $locale;

    #[ORM\ManyToOne(targetEntity: \Document::class, inversedBy: 'translations')]
    private Document $entity;

    public function getLocale(): string
    {
        return $this->locale;
    }

    #[ORM\Column]
    private string $text;
}

text, locale and entity are all private, yet they're never set. Is this something that happens in the constructor? Or a listener somewhere? I'm confused as to how it works.

On a related note, while I understand what text and entity are, they're confusing (to me) in the documentation. Text and Entity are also types. Would you consider changing the field names to 'title' and 'description' (a string and text field) and changing the documentation to use those names instead? getText() to me too generic, it's hard to remember that it's the text field, not the text of the document, would would be of a text type, but a string in your example, so when you say document->getText() you're only getting a 255 character field in most databases. Thus my confusion.

shouldn't $locale be protected? I dunno, I'm just stabbing here. Is there a public repo that uses this, if I can see it in action I'm sure I can figure it out.

Thanks! I look forward to using this.

I submitted a PR that adds namespaces and more use statements.

[tacman]

Hi, this is such a cool bundle, I've worked with the translation component of both doctrine behaviors and doctrine extensions, and I'd love to give this a try, but I'm stuck on the configuration.

Would it help if I checked in a demo repo? My classes are following your README instructions, but I'm still stuck.

Thanks.

[mpdude]

Hey @TAC, sorry for the delayed response.

To my knowledge, there is no public repo that shows usage, but we're actively using this bundle in about a dozen of projects (closed source).

I'll see what I can do to make the documentation more understandable.

Regarding the DocumentTranslation entity class that you showed above: This class is used by the bundle to hold translated field values. When you add a new translation to a Translatable instance, the bundle will create a new instance of this class and store all necessary values in its field through reflection.

As I remember it it should be fine to make all fields private and not provide any getters or setters. Your code should not need to deal with DocumentTranslation instances directly.

If you have any suggestions how documentation could be improved, let us know or open PRs.

[tacman]

I've added the classes (Document and DocumentTranslations) from README almost exactly (I tweaked the classes so they'd compile). And create a fixtures file.

If you can fix this repo, one of us can update the website. Can you update the AppFixtures.php that shows an example of how to add a translation?

Thanks!

This uses sqlite, so these 4 lines should show the error. It's using dev-master of the polyglot-bundle

git clone [email protected]:survos-sites/polyglot-readme.git && cd polyglot-readme
composer install
bin/console doctrine:schema:update --force
bin/console doctrine:fixtures:load -n 

                                                                                               

   > purging database
   > loading App\DataFixtures\App
   > loading App\DataFixtures\AppFixtures

In CacheItem.php line 139:
                                                                                               
  Cache key "App\Entity\Document$WebfactoryPolyglot" contains reserved characters "{}()/\@:".  
                                                                                               

doctrine:fixtures:load [--append] [--group GROUP] [--em EM] [--purger PURGER] [--purge-exclusions PURGE-EXCLUSIONS] [--purge-with-truncate]

[mpdude]

Can we close either #61 or #64?

[tacman]

Yes, I'll update the README with the entities you fixed in my demo repo.

Alas, I didn't realize that the bundle was tied to a single language, and there's a fork of the DoctrineBehaviors that supports Symfony 7 so I went back to using that.

Plus, I use ApiPlatform for the api, and I'm not sure that this bundle would support that.