genkgo / mail

Library to send e-mails over different transports and protocols (like SMTP and IMAP) using immutable messages and streams. Also includes SMTP server.
https://mail.readthedocs.io/
Other
402 stars 21 forks source link

Buffing the initial readme documentation #105

Closed bobmagicii closed 1 year ago

bobmagicii commented 1 year ago

I've worked through it, but the readme I think could use more verbosity. For example it says "Send message quick and easy" then has a code sample where the classes are referenced flatly without their namespace paths, nor the use statements required to make them work flatly as shown in the readme.

image

I only nag about this because I feel your classes are super duper maybe borderline overly spread out, in non obvious ways. To get these I ended up having to fallback to the github repo search.

frederikbosch commented 1 year ago

Thanks for the suggestion. Closed by commit e54eb9a.

I feel your classes are super duper maybe borderline overly spread out

You are free to feel whatever you want, but I have intentionally spread them out. This library includes a SMTP server and client and a IMAP library and client. It contains many methods of sending messages over transports. It contains queueing etc etc. Moreover, all classes are tested. I'd even say more than 99% of the lines code are tested. All other libraries I used in the past were often very very messy. E-mail is simply not an easy format, not easy to transport, not easy to receive. It requires many pieces, that need their own responsibility in code.

You are also free to wrap these classes and create a more easy-to-use class. My code that is using this library often looks something like this. I am very happy with that.


<?php

use Genkgo\Mail;

class Someting {

    public function __construct(private Mail\TransportInterface $transport) {}{

    public function sendMessage(User $user): void
    {
        $message = (new Mail\MessageBodyCollection('<html><body><p>Hello World</p></body></html>'))
            ->withAttachment(new Mail\Mime\FileAttachment('/order1.pdf', new Mail\Header\ContentType('application/pdf')))
            ->createMessage()
            ->withHeader(new Mail\Header\Subject('Hello World'))
            ->withHeader(Mail\Header\From::fromEmailAddress('from@example.com'))
            ->withHeader(Mail\Header\To::fromSingleRecipient('to@example.com', 'name'))
            ->withHeader(Mail\Header\Cc::fromSingleRecipient('cc@example.com', 'name'));

        $this->transport->send($message);
    }
}
bobmagicii commented 1 year ago

yeah, awesome.

sorry i didn't mean to seem like i was nagging, so much as i felt the gravity of the readme being more verbose was super important and that was how my story telling skills elected to proceed. even though i literally said i was nagging heh.

was a bit frustrated with my ide's failure to index properly, methinks.