Problem/Motivation:

PROBLEM 1: The README.md doesn't contain enough documentation that clarifies these points (it contains just some hints) :

  • How to create fixtures?
  • How to create fixtures groups?
  • How to share object between fixtures?
  • ...

new Feature :Create a new submodule that contains some examples so that a user can follow them easily.

Proposed solutions:

PROBLEM 1 SOLUTION: Adding some code snippets and documentation with easy to follow steps to the README.md that clarify these points :

  • Creating and loading fixtures
  • Sharing objects between fixtures
  • Loading the Fixture Files in Specific Order
  • Using Fixture Groups to Only Execute Some Fixtures
  • Using the drush content-fixtures:load to load all fixtures OR specific fixture group
  • ...

PROBLEM 2 SOLUTION: create content_fixture_example module and add some code examples:

  • An example that indicates how to share object between fixture & how to load them in a specific order
  • Another example indicates how to assign a set of fixtures to a specific group
  • Last one just of how to create a set of fixtures with a simple for loop

Issue fork content_fixtures-3257306

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

Mario_o created an issue. See original summary.

luke_nuke’s picture

luke_nuke commented

Hello! Thanks for your feedback. content_fixture_test module is not supposed to have examples, this module just provides some features for tests, and it is its only purpose.

Documentation assumes some pre-existing knowledge of Drupal/Symfony's services and tagging, and it surely could be improved. I might add a dedicated example module to the codebase if that would help.

Note that there are `drush help` commands specified in the readme, where you might get some details regarding usage of groups for example.

Mario_o’s picture

Mario_o commented
Issue summary: View changes
Mario_o’s picture

Mario_o commented
Issue summary: View changes

Mario_o opened merge request !1

luke_nuke’s picture

luke_nuke commented

Thank you for your contribution! It's very appreciated. I went through the updated README.md and added some tweaks/clarifications. Before merging it, I think I will take the opportunity and add some commonly used patterns to the example module. For example: generating images.

I have two questions though:

  1. I noticed that you added yourself to the list of maintainers in the README. I consider it a commitment to an ongoing effort of supporting this module. Did you really mean that?
  2. I noticed that you used "@author" tag in the example module's classes docs. To be honest, I'm not a big fan of this tag, because as time passes, and new commits arrive, it's difficult to track all authors in these tags, and all this information is tracked anyway in the commit history. Some time ago Apache Foundation even enforced removal of all @author tags from their projects because of that, and I share this sentiment. It doesn't matter that much in this small module, but would it be okay for you if we would remove these tags, and try to avoid them for the purpose of reducing noise in the code?

Once again: thank you for your contribution, it was much needed.

Mario_o’s picture

Mario_o commented
  1. for the first question yeah exactly, I think the module is great and can grow bigger with more additional features, so I will be really happy to make this commitment to fix bugs, add features, add more documentation, and even video tutorials if necessary( the easier to understand the more people will use it).
  2. for the second question, it is just a habit you can remove the @authro tags.

Happy to work together toward a greater module, that can grow faster over time with the right contribution :) .

luke_nuke’s picture

luke_nuke commented

I did some tweaks to the docs of the example module to reduce repeated statements, group them in places they fit better, like in the methods docs, etc. I also added an example of image generation with a test. I think it should be good to go, but I will give it a moment, to make sure I didn't miss anything.

luke_nuke’s picture

luke_nuke commented
Status: Active » Needs review
Mario_o’s picture

Mario_o commented

for the ImageProvider, it will be better to include the logic of generating content in the content_fixtures module itself and rename it to DataGenerator why?

because in the future features we can add more methods to the DataGenerator service factory that enable us to generate other type of data ,like for example:

// create an image file using specific style, then Assign it to media
$this->dataGenerator->generateMediaImage($img_style,..)
// Generate a paragraph of specific bundle 
$this->dataGenerator->generateParagraph($bundle,$values,  ..)

we can even go further and make the data Generator factory service use an extra layer : fzaninotto/Faker package to generate close to real world data fixtures.

The big advantage here that the dataGenerator service factory can be used in 2 ways :

  1. To create fixtures, that looks like the real data.
  2. Extend the module functionality , since a developer can use the dataGenerator helper methods to use some generic helpers
luke_nuke’s picture

luke_nuke commented

It would be less flexible though, because it would couple logics that don't need to be coupled. If fixture needs a generator, it probably doesn't need every generator. Generators being independent units make for a more flexible design: end user can group them in higher level logical units as he wants. He can implement this kind of a "super-generator" you described by just injecting existing generators to it, and he can even make it configurable, and make generator implementations switchable. This gives him much more power. Or in other words: Coupling them in a single class would make them always move around together, and that's just less flexible. Also adding new methods to the interface of such "super-generator" would always break backwards compatibility, because someone could use this interface. That's why I don't see any gain from it. Currently we have existing namespace for generators, user can inject them as he needs them, and we can add new in a non-BC-breaking way, so it seems perfect.

Edit: Sorry, we have namespace and a generator in example module only. But I'm not sure if we need generators in the main module to be honest, because they could be very project specific, and some of them would require external dependencies, like a PDF generation. I think it should be up to developers to implement their own generators, because implementing them in this module and aiming for all possible requirements would probably prove to be difficult. So I consider going beyond the example image generation based on Drupal's core features to be out of the scope of this module for now.

We could make an online documentation with some arbitrary examples though.

luke_nuke’s picture

luke_nuke commented

Let's consider other possibility: creating a supplementary module named, for example: content_fixtures_tools . Let's say you would want to implement as many useful generators as you can. PDFs, pulling images from the external services, images in many formats, Office's documents etc. You would end up with a lot of external dependencies. Would it be wise to install a module that makes your code base that much heavier? I think not. It also wouldn't be easy to maintain such dependencies, taking into account security updates etc. That's why I prefer guidance in implementing custom generators instead of implementing them for everyone.

Mario_o’s picture

Mario_o commented

Yeah I get the point and I didn't think abut this points ,

so I think you are right it will be better to include just an example and let the user create his own generators .

  • Luke_Nuke committed 4158dae on 3.0.x authored by Mario_o 
    Issue #3257306 by Mario_o, Luke_Nuke: Add a detailed module...
luke_nuke’s picture

luke_nuke commented
Status: Needs review » Fixed

Merge request has been merged! 🎉 Thank you for your initiative and help!

Mario_o’s picture

Mario_o commented

Greate happy to hear that :)

luke_nuke’s picture

luke_nuke commented
Status: Fixed » Closed (fixed)