Create Icon Captcha API for Integration with CMS and Commerce Platforms

[joshsedl]

First off, I have to give props to this wonderful self-hosted Captcha Plugin! The looks, feel and simplicity are just great, as well as the customizability and self-hosted nature.
My company and I were just in the midst of implementing Icon Captcha as a Drupal CMS module, when we realized, this is not possible with the current version of this plugin, as it uses its own session objects internally. This approach is great for pure HTML / PHP Sites but (usually) not suitable for CMSs, Commerce Platforms and some Frameworks (like WordPress, Drupal, Shopware, Symfony etc.) as they work with their own session object.

As of this, I would kindly ask if it was possible to create a separate fork / repository for an IconCaptcha API, where the session logic is split from the icon captcha logic, so it would be possible to inject your own session to work with. Alternatively, this could also be realized in this repository for a 4.x release, where we split the logic into the mentioned 2 Layers, so people can either use the plugin as is or hook in between the session → icon captcha communication and inject their own session.

My company and I would provide help to realize this change if necessary. It would help us a lot and open the gates for others to implement their own Framework / CMS / Commerce implementation of this beautiful plugin!

Here is the Link to our current (not working) Drupal module implementation: https://www.drupal.org/project/icon_captcha

Cheers!

[JPustkuchen]

Thanks @joshsedl for creating the issue!

I think there are several use cases where IconCaptcha could help in Frameworks, eCommerce and CMS if we could split off an API layer and put the current standalone implementation on top of it.
The JavaScript part is already fine, so we're only talking about the PHP implementation, which currently seems to be focused on the standalone implementation.

We like the IconCaptcha solution, so I would much more like to have a 4.x with an API / SDK layer than forking something off here. Win-win for everyone :)

So we're not asking for you to do this, but if you'd agree this would make sense and you would like to build this together in a 4.x branch with us.

Looking forward to the maintainer feedback :)

[fabianwennink]

Hi @joshsedl and @JPustkuchen! I'm not sure I fully understand your issue. The session object is nothing more than just a separate class, containing some helper functions to make writing to the session easier. Are you saying Drupal can't work with classes? Regardless of if the PHP classes would be separated from the other code in this repository, the captcha state still has to be stored somewhere - which in this case is the session. Could you please elaborate your issue a bit more, as my experience with Drupal is near zero.

[JPustkuchen]

@fabianwennink thanks a lot for your quick response! We'll come back here as soon as possible, very busy days.

To be clear: We don't want to say anything is bad here! :) We REALLY like the plugin, just want to make it even better, more flexible and integrable with you, so please don't see any criticism here. You've done a great job, and we'd like to help to make it even greater and better, reusable for further situations.

The problems with the current implementation and reuse in CMS's / eCommerce systems is that the library wasn't written to provide a flexible API (defined reusable methods) to be integrated into larger building blocks of existing systems. In the current state, it's a more standalone block, which works great for example for existing custom PHP websites.

That should be kept!
But we need an API level below the standalone implementation which allows splitting the few main functionalities into public methods and hide the internal parts of the API. Global dependencies like the session should not be created or started in the API code, but instead be injected from the calling party (or be created separately by a helper method from the API). So one concrete example is, that in most situations the CMS's and eCommerce systems already have an existing session with data and restarting the session is not allowed.

Furthermore, the current implementation isn't wrappable, as it's not an API, but standalone. For security reasons, CMS's like Drupal disallow (by .htaccess) to execute .php files, so we need to implement the controller the Drupal way and then call the API method to for example generate the captcha. This isn't possible currently, things are bound tight.

I understand that this might not be easy to understand, so perhaps it would be best to create a fork with some examples and work on it together?

And as a first step, we should figure out which API methods we need here. For example:

• create()
• render()
• validate()
• reset()

Here's an example of the Google reCaptcha API methods:
https://cloud.google.com/recaptcha-enterprise/docs/api-ref-checkbox-keys

Here's another example, which only provides a "create()":
https://github.com/produck/svg-captcha
So this could be even more simplified, if storing the correct answer isn't a job of the API, which just returns the riddle and the correct answer to check?

Once that API exists, the current standalone version can be rewritten calling these APIs and providing a public API file.

BTW this will also solve the issue with
#14 (comment)

The IconCaptcha Library / API is what composer integrated. The public .php file is the standalone implementation, which calls this dependency but is not provided by composer, instead has to be placed and configured by the user in the webserver directory.

Hope this helped a bit :)

[JPustkuchen]

@fabianwennink any questions so far? Happy to help where I can with the concept. Hope one can understand what I wrote above... feel free to ask otherwise :)

[fabianwennink]

@JPustkuchen A lot of changes have been made to the API so far, which can be viewed in the develop branch. The IconCaptcha class (main class) is now practically only a facade, with 2 public functions. Basically, the whole class structure has changed, allowing for several internal features (such as the session storage) to be changed with custom implementations via the captcha options, see the example down below.

'token' => \IconCaptcha\Token\Token::class, // implements TokenInterface
'session' => \IconCaptcha\Session\Session::class, // implements SessionInterface

Note that the default classes provided with the plugin will still utilize the global session.

Regarding the 'request' file, the captcha-request.php file in it's original form, no longer exists. This code has been moved to its own class, with public functions which can be implemented in whatever way you like, e.g. in a controller. As an example, take a look at the remaining captcha-request.php file in the examples folder for standalone implementations.

I think these changes are in line with your wishes for the API, and also those of @joshsedl. Let me know what you think of these changes! I'm still actively developing the next version of IconCaptcha, so nothing is definitive yet. However, the general separation of responsibilities to different classes with possibilities of overriding the default implementations will remain.

[joshsedl]

@fabianwennink well done! Very clear and well documented code! @JPustkuchen and me just discussed the changes internally and only found a couple of small issues here and there while reviewing the code the first time!

Once these issues are resolved, we will try to implement the icon captcha module for Drupal. When implementing, we will see if any further adjustments are needed, and we'll come back to you then. 👍

Happy coding!

[fabianwennink]

Feedback issues created by @JPustkuchen, linking them here to keep the discussion in 1 issue.

• Do not use $_SESSION directly outside of the Session Class #22
• Make session_start() a Session Interface Method? #23
• Make session data reliable / explicit #24

(all closed, to keep the discussion in just this issue)

[fabianwennink]

Hi all! I just wanted to post a quick update on the state of the upcoming release of IconCaptcha 4. After about a year of on-and-off development, the renewed code base is pretty much ready to be published. All that is left for me to do is double check and test everything, and to update the wiki documentation. I already made some progress on that, but a large portion still needs to be updated.

Now, the next 2-ish weeks will see basically no changes being made to either the code and docs, as I'll be enjoying my well-earned vacation. After that, I'll make sure to finish everything so that IconCaptcha 4 can be released early to mid-October. So just hang on a little bit longer, and until then, feel free to try out the IconCaptcha 4 development version.