Documentation
dlearningfr opened this issue · comments
While your website is down, we do not have access to documentation.
Could you give us access to the documentation in any way ?
Thank you for your amazing work there.
Hi @dlearningfr, thank you for highlighting this, it was brought up before at #99.
I am personally not sure where the docs are located for the package that the website ran on, but it would be great if we could start bringing it back up.
@Qoraiche would know more about where those are at currently or if it was a little more custom than regular docs systems :)
I was going to suggest that there is the option of making use of the https://laravelpackages.org website which uses GitHub's pages functionality to give a custom url for Laravel related packages.
I am not sure if Alex would have any invite codes available, but the usage of it is straight forward and we could use a separate repo for the docs or the /docs dir on this repo and exclude it in the export ignore defs.
/cc @alexjustesen if the cc is okay to ask you :)
@ReeceM thanks man.
I'll be opening up https://laravelpackages.org to the masses next week so invites are closed for now. Best to follow laravelpkgs on Twitter for updates.
That's awesome @alexjustesen, also glad I did check in a way.
It's good to know then. Hopefully we can move the docs for this over there. Or have a fallback to it. 👍
Any updates on the documentation?
According to issue #99 the documentation is offline for over a year now.
Hi there @jornwildenbeest, at present there isn't an immediate update about the current state of the documentation. It is unfortunate that it has been unavailable for a period of time and possibly discouraging to end users.
For the time being is there something specific that you need help or direction with regarding the package? I am happy to help and answer questions you have.
Hi @ReeceM, thanks for your quick response!
There is nothing you can help me with right now.
I was just wondering if the documentation will be available any time soon.
Since I have an application that sends out mails to different clients, I was trying to see if I could use this package to handle the e-mail templates so they can be dynamic and users can change them.
Havent tried the package yet, so I will do that first!
Hi @jornwildenbeest, with regards the docs being available soon, I am looking at documenting the functionality over the next few days. So they should be initially available in the readme or a docs dir.
With regards to your use case, I am not sure if you are wanting users to edit individual templates and be scoped to what they can see. That isn't immediately available in the package as there isn't a way to limit what templates / mailables are visible.
If the users on the other hand can see all the templates, and are supposed to be editing them, then the if you have it on a production server, for the time being you might need to sync what is written to the disk on the server back to the git repo. As it currently does write to the app/ dir for the JSON template file. (#21 refers to the DB being used, and this may be a solution in the way of allowing exports and syncs if there is a production install)
Hi @ReeceM,
For the time being, me and my colleagues are the only ones editing the templates. so there is no "restriction" per user needed for now. maybe in the future but not for now.
Right now we are editing the templates within .blade.php files. So every time we have to change a template, we have to edit the template, push to git and then deploy to live.
I was hoping we can speed up that process with this package because you don't have to deploy the templates anymore.
With regards to the templates written on the disk, thats not a big problem!
I will try the package and let you know if I have any more questions. Thanks!
Hi @jornwildenbeest,
The current use that you and your team will be using it will definitely work in having just the team. For pushing to git you would still have to do that when saving the final templates, but if you are editing them, using the git repo to sync between dev will work as the config file is saved to the disk under the Mail dir. Once that has been shared, another dev can see the links between templates.
I think maybe using this issue to track the docs. Can we make use of https://docusaurus.io for the docs of the package? We can integrate it into the package, make sure it's also in the export-ignore to reduce the size of the package. We can then use the laravel packages site to host it.
Also would it be possible to get access to the older docs? Can't find a webarchive version of it.
Hi @ReeceM,
Yes, that would be great, unfortunately, I have lost all the docs we had in maileclipse.io :\ , but it's okay, your idea is awesome we can make use of https://docusaurus.io and start iterate on it starting with an installation page
Hi @Qoraiche
No worries about the docs 👍. I think an installation page and basic troubleshooting then would be a good place to start.
I forgot to note that Docusaurus uses React, there is also VuePress that runs with Vue. I think the only thing then would be the preference for the repo for being maintainable. They both basically run on markdown, the libraries are the only difference.
You can also check https://www.gitbook.com @ReeceM
Gitbook is good but that there are a few must use features that need an upgrade :/ so I think we'll go with an open-source solution like Docusaurus, I will set it up this week with the repo and map it with the Maileclipse domain.
Thank you guys for your suggestions
Gitbook is good but that there are a few must use features that need an upgrade :/ so I think we'll go with an open-source solution like Docusaurus, I will set it up this week with the repo and map it with the Maileclipse domain.
Thank you guys for your suggestions
I have some of the Docusaurus file structure setup at the moment, just haven't pushed it yet as I was still working on it, but also had a some stuff to attend to.
Should I push it up then rather then there is the base to work or adjust from?
Gitbook is good but that there are a few must use features that need an upgrade :/ so I think we'll go with an open-source solution like Docusaurus, I will set it up this week with the repo and map it with the Maileclipse domain.
Thank you guys for your suggestionsI have some of the Docusaurus file structure setup at the moment, just haven't pushed it yet as I was still working on it, but also had a some stuff to attend to.
Should I push it up then rather then there is the base to work or adjust from?
Awesome 👏 yes you can push it whenever you feel ready to do so, just wondering do we have a basic start installation page and basic troubleshooting? because like that we can start iterate on it easily.
Gitbook is good but that there are a few must use features that need an upgrade :/ so I think we'll go with an open-source solution like Docusaurus, I will set it up this week with the repo and map it with the Maileclipse domain.
Thank you guys for your suggestionsI have some of the Docusaurus file structure setup at the moment, just haven't pushed it yet as I was still working on it, but also had a some stuff to attend to.
Should I push it up then rather then there is the base to work or adjust from?Awesome 👏 yes you can push it whenever you feel ready to do so, just wondering do we have a basic start installation page and basic troubleshooting? because like that we can start iterate on it easily.
I had started with an intro and getting started, but hadn't done any troubleshooting page.
Hey @ReeceM, I have a question about passing variables to a mail class.
When you visit the /maileclipse/mailables overview, the mail class which extends Mailable requires an "Mocked" class in the construct method.
I have my own "Submission" class where the data is stored that needs to be send in the mail.
I used to pass the Submission class in the construct method but with the laravel-mail-editor package that doesn't work anymore since the overview page will break.
Is it possible to somehow convert this class into the Mocking class or something or what are the expectations here from the laravel-mail-editor package?
Do you have an example with this Mocking class?
Hi @jornwildenbeest, is okay if I get back to on this a little later today? Just busy with something at the moment, so wouldn’t be able to give you a good answer/example on a phone
@ReeceM Yes of course!
Hi @jornwildenbeest,
Below is my reply, also please let me know if there is anything that is unclear, or you would like a further answer to or if I missed it 😄.
Hey @ReeceM, I have a question about passing variables to a mail class. When you visit the /maileclipse/mailables overview, the mail class which extends Mailable requires an "Mocked" class in the construct method.
It shouldn't be requiring the Mocked class by default, the __construct method usually has what is put in there by the end user, but the Mocked class is injected. So if it can't resolve the type of the argument, it will instantiate the mail class with the Mocked class which is a morphing object with memory. (It basically learns what you calling/ have called)
I have my own "Submission" class where the data is stored that needs to be send in the mail. I used to pass the Submission class in the construct method but with the laravel-mail-editor package that doesn't work anymore since the overview page will break.
I think this is related to it not finding the type hint. The package defaults to giving a null value which can't have anything called. So I suspect then that the Submissions class isn't a model or something that can be resolved through type hints. (Although I can't recall the package looking in the app(...) singletons and such, I will check this, if not might be useful to look there for bindings then, just hopefully they don't need constructor stuff)
Is it possible to somehow convert this class into the Mocking class or something or what are the expectations here from the laravel-mail-editor package?
I don't think it's possible to create a class that extends the Mocking class, it's sort of an object that morphs, you can find the package on https://github.com/reecem/mocker if you want to see the functioning bit, the searcher is a bit dotty at the moment, so it isn't used in this package.
Do you have an example with this Mocking class?
The mocking class is basically going to do this:
This would be a mailable class, note $something doesn't have a type hint.
class NewUserMail extends Mailable
{
public $something;
public $user;
public $total;
public function __construct(User $user, $something, int $total)
{
// if you assign to the $something internally here
$this->something = $something;
$this->something->data->object->listing = 3;
$this->something->data->object->meh = 'abc';
}
// render function
}The mailable blade would end up like this.
{{-- mailable --}}
1: {{ $user->email }}
2: {{ $something }}
3: {{ $something->data->object->listing }}
4: {{ $something->data->object->meh }}
5: {{ $something->hello }} {{-- This didn't get a value assigned or wasn't on the object --}}
6: {{ $total }} The resulting html/text would be:
1: email@example.com
2: something
3: something->data->object->listing => 3
4: something->data->object->meh => "abc"
5: something->hello
6: 1024 If you were to give $something a type hint to custom class, so Submission it would fail as the package doesn't instantiate that properly. Or know what it is.
I can't remember if at some point it did override the type hint and give a default or not.
So with regards the Submission class that you use, if it isn't given a type hint it will automatically be assigned the Mocked class. But obviously for your end, removing that would be that there can't be static analysis or type errors from PHP unless you use the docblocks to give the IDE hints and stuff.
Are you wanting specific values to be coming from the Submission class? So if you are say calling $submission->some_method() you would like to see that it has the kind of correct data?
As an aside, that could be solved if this is an issue by either supplying constructor args in the docblocks or something like that. Or even a trait that can be added to classes that you can define the constructor args needed. So the package could do:
$traits = (new ReflectionClass($arg))->getTraits();
// search traits for the function and call to be safe.
or
if method_exists($arg, '__mailable_constructor')
then call Reflection classes with the resolved array values.
Hi @ReeceM, Thanks for your reply! Don't think I have the time to check it out today so I will check it out tomorrow or the day after that.
Hi @ReeceM,
So my main problem is that when I try to use my Submission class within the Mail class like this:
class EclipseMail extends Mailable
{
use Queueable, SerializesModels;
public $submission;
/**
* Create a new message instance.
*
* @return void
*/
public function __construct(Submission $submission = null, array $config = null, String $locale = null)
{
$this->submission = $submission;
}
I get the following error when I try to access /maileclipse/mailables/
Argument 1 passed to App\Mail\EclipseMail::__construct() must be an instance of App\Submission or null, instance of ReeceM\Mocker\Mocked given
Because when loading the mails within /maileclipse/mailables/, it automatically passes the class Mocked as the first variable in the constructor, but because i want it to be Submission, it breaks..
Any idea how to fix this?
And Submission is just a class like this:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
class Submission extends Model
{
use SoftDeletes;
protected $table = 'submissions';
protected $fillable = ['first_name', 'email', 'last_name', 'data', 'locale', 'admin_email_receiver', 'admin_cc_email_receiver', 'subject'];
}
Hi @jornwildenbeest,
I think because it can’t find a factory instance of the model, it reverts back constructing the mailable with the fallback class Mocked
if you try adding the trait for the factory helpers and also create a factory it might help fix that.
Also I think this might need a soft error that lets someone know that the Model doesn’t have a factory. Given that it is a Model class.
if you try adding the trait for the factory helpers and also create a factory it might help fix that.
Where do I need to addd this trait? I'm sorry I'm not familiar with traits.. And I'm not really sure why I need to create a factory for the model to get this to work?
if you try adding the trait for the factory helpers and also create a factory it might help fix that.
Where do I need to addd this trait? I'm sorry I'm not familiar with traits.. And I'm not really sure why I need to create a factory for the model to get this to work?
Hi @jornwildenbeest, sorry for responding a little late.
You would add the trait if you are using Laravel ^8.x, or if you have lower you would create a Factory. To add the trait, you can included it after the SoftDeletes trait.
You can read the Laravel docs on that: https://laravel.com/docs/8.x/database-testing#defining-model-factories
So it would end up like use SoftDeletes, HasFactory; You would add use Illuminate\Database\Eloquent\Factories\HasFactory; as a class use statement.
And I'm not really sure why I need to create a factory for the model to get this to work?
So the package needs the Model to have a Factory because it tries to provide realistic data to the methods and variables on the Model based on what you expect in the email, so if it's Hi {$user->name} you get 'Hi Joe Soap'. If it's $billable->street_address you get '1st Street' instead of getting random garbage.
This is really only needed when you are using Models in the mailable.
I hope that is clear? If not please let me know. :)
To the above:
Your class would look like this:
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\SoftDeletes;
+ use Illuminate\Database\Eloquent\Factories\HasFactory;
class Submission extends Model
{
+ use SoftDeletes, HasFactory;
protected $table = 'submissions';
protected $fillable = ['first_name', 'email', 'last_name', 'data', 'locale', 'admin_email_receiver', 'admin_cc_email_receiver', 'subject'];
}
Hi @ReeceM,
Sorry for the late response! I had to work on another project.
But the solution you gave me worked fine!
I ended up adding the trait, creating the factory and after that it was working fine.
Thanks!
Hey @jornwildenbeest,
All good, I am glad it is sorted for you 👍 :)
Guys I got the same error Too few arguments to function
Too few arguments to function App\Mail\ChangeEmailRequest::__construct(), 0 passed in D:\Laravel\grand\grandcalendar-api\vendor\qoraiche\laravel-mail-editor\src\MailEclipse.php on line 796 and exactly 2 expected
it's displayed for any attribute in my contract
<?php
namespace App\Mail;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Mail\Mailable;
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Illuminate\Queue\SerializesModels;
class ChangeEmailRequest extends Mailable
{
use Queueable, SerializesModels;
public $otp;
public $userName;
/**
* Create a new message instance.
*
* @return void
*/
public function __construct($otp, $userName)
{
$this->otp = $otp;
$this->userName = $userName;
}
/**
* Get the message envelope.
*
* @return \Illuminate\Mail\Mailables\Envelope
*/
public function envelope()
{
return new Envelope(
subject: 'Verify Change Email Request with OTP ',
);
}
/**
* Get the message content definition.
*
* @return \Illuminate\Mail\Mailables\Content
*/
public function content()
{
return new Content(
markdown: 'emails.users.changeEmailRequest',
with: [
'otp' => $this->otp,
'userName' => $this->userName,
],
);
}
/**
* Get the attachments for the message.
*
* @return array
*/
public function attachments()
{
return [];
}
}
#208 - Duplicated, up coming fix on v5