Note: this discussion is scheduled for the 1.5.0 release, because the current changes done to that API have not been released yet

#270 and #315 have introduced a CompilationResult. However, this change currently has a few drawbacks:

• the way it is implemented (changing the return type of Compiler::compile) is technically a BC break. The fact that object is castable to string helps, but only if such a cast actually happens before a strict string check is done (and if no cast is done before returning it from the embedded, which is likely if you don't modify the string after compilation, this leaks in the signature of the embedder).
• the CompilationResult is currently responsible for writing the sourcemap to the filesystem, due to this BC layer. This makes it a bit weird (the object is meant to be a value object). It also makes it harder for embedded projects that want to customize where the files are written (they might be written to a CDN rather than on the local filesystem)

If we want to solve that, I think we need to keep the Compiler::compile() method as it is in 1.4.1 (i.e. returning a string) and introduce a new modern API instead.
My proposal is to use compileString(), which is the equivalent name in dart-sass for the API taking a string as input (their compile() function takes a path as input and reads the file content internally).

Regarding the handling of the sourcemaps, I looked at dart-sass for inspiration:

• the Dart API of compile/compileString returns the CSS as a string without any # sourceMappingURL comment, and takes a callback as argument receiving a SingleMapping object from the official Dart source_maps package. The API does not support any option to configure the generated sourcemap. They expect the caller to modify the object before dumping it in their callable.
• the JS API (inherited from node-sass) returns a result object, where css is the CSS with its # sourceMappingURL comment (meaning that the JS API includes options to control the sourcemap, similar to our options) and map is the source map as a string (so already json-encoded). However, when asked to not embed the sourcemap as a data-uri, it does not write the map to the filesystem. The caller is expected to do it.

Given that PHP does not have a canonical sourcemaps package, I suggest going in the direction of what the JS API does. This would basically be the API of #315, except that the file would not be written to disk automatically. The caller would be responsible for that based on their own needs (if the use SOURCE_MAPS_FILE for their config).